# Logging
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/backoffice-api/logging
Retrieve Zylon platform logs manually from the Backoffice API.
The Backoffice Logging endpoints let authorized Backoffice users retrieve stored Zylon logs for investigation, review, export, or integration jobs.
This page covers manual retrieval only. For external syslog or HTTP delivery, see [Log Delivery and Storage configuration](/en/v1.57/operator-manual/configuration/features/log-delivery-storage).
These endpoints are read-only. The documented API exposes `GET` operations for listing stored logs and usage data; it does not expose per-record update, patch, or delete operations.
## Authentication and permissions
| Requirement | Value |
| - | - |
| Authentication | Account token or account session |
| Role | At least the `operator` role |
```bash theme={null}
curl "https://{BASE_URL}/v1/platform/logs?page=0&page_size=50" \
-H "Authorization: Bearer {API_TOKEN}"
```
Workspace-only tokens are not enough for these endpoints.
For operator-facing guidance on governance, evidence preservation, and SIEM delivery, see [Auditability & AI Governance: Logging, Evidence, and SIEM Delivery](/en/v1.57/operator-manual/backoffice/log-delivery-storage).
## Endpoints
| Endpoint | Purpose |
| - | - |
| `GET /v1/platform/logs` | List stored platform logs across gateway, workspace, security, and backoffice event families. |
| `GET /v1/platform/gateway/{gatewayId}/logs` | List stored logs for one gateway. |
| `GET /v1/platform/usage` | Return limited AI usage data for usage charts and token/tool analysis. |
## Pagination
The two log list endpoints return a page envelope:
```json theme={null}
{
"data": [],
"next_cursor": "01985a54-2f4d-7000-8001-4d7f7a6d9a10",
"previous_cursor": null,
"has_next_page": true,
"has_previous_page": false,
"total_count": null
}
```
Supported page parameters:
| Parameter | Description |
| - | - |
| `page` | Zero-based absolute page index. Cannot be combined with cursor pagination. |
| `page_size` | Absolute page size. Default is `50`. |
| `page_order` | ID tie-breaker order used by pagination. |
| `after` | Cursor for forward pagination. |
| `before` | Cursor for backward pagination. |
| `first` | Forward cursor page size. Default is `50`. |
| `last` | Backward cursor page size. |
| `total_count` | Set to `true` to include `total_count`. |
Logs are ordered by `start_timestamp` descending. The backend adds log ID ordering as a stable tie-breaker.
## Shared log filters
`GET /v1/platform/logs` and `GET /v1/platform/gateway/{gatewayId}/logs` support these query parameters:
| Parameter | Description |
| - | - |
| `gatewayId` | Match logs for one gateway. On the gateway route, the path value overrides this query value. |
| `tokenId` or `token_id` | Match logs created through one API token. |
| `event` | Match one event family: `zylon.gateway.http`, `zylon.gateway.chat`, `zylon.gateway.embed`, `zylon.gateway.ingest`, `zylon.workspace`, `zylon.security`, or `zylon.backoffice`. |
| `action` | Match one action, such as `ws.project.create`, `ws.interaction.create`, `backoffice.api_token.create`, or `security.auth.invalid_token`. |
| `organizationId` | Match one organization. |
| `projectId` | Match project-linked workspace or security logs. |
| `start_date` | Unix epoch milliseconds. Matches logs with `start_timestamp >= start_date`. |
| `end_date` | Unix epoch milliseconds. Matches logs with `end_timestamp <= end_date`. |
| `include` | Comma-separated list of heavier fields: `InputPayload`, `Payload`, `Data`, `ChatRequestParameters`, `ChatRequestMessages`, `ChatResponse`. |
Without `include`, `input_payload` and `payload` are returned as empty objects and `data` is omitted. Use `include=Data` for structured per-event data. Add chat-specific include values only when needed.
The `include` parameter controls retrieval shape only. It does not enable or disable collection. If request messages or responses are present in stored chat logs, they are returned only when the caller requests the corresponding include value.
Retrieving very large chat logs can take time, especially when the requested scope is large or when messages and responses are included.
## Event families and actions
| Event | Description |
| - | - |
| `zylon.gateway.http` | Gateway HTTP request logs. |
| `zylon.gateway.chat` | Gateway chat usage logs. |
| `zylon.gateway.embed` | Gateway embedding usage logs. |
| `zylon.gateway.ingest` | Gateway ingestion usage logs. |
| `zylon.workspace` | Workspace audit logs for projects, users, files, chats, integrations, and hard delete activity. |
| `zylon.security` | Authentication and authorization security logs. |
| `zylon.backoffice` | Backoffice account, API token, and log retrieval audit logs. |
| Action | Category | Description |
| - | - | - |
| `ws.project.create` | Workspace | Project created. |
| `ws.project.update` | Workspace | Project updated. |
| `ws.project.delete` | Workspace | Project deleted. |
| `ws.project.member.add` | Workspace | Project member added. |
| `ws.project.member.leave` | Workspace | Project member left. |
| `ws.project.member.remove` | Workspace | Project member removed. |
| `ws.project.member.role.update` | Workspace | Project member role updated. |
| `ws.project.ownership.transfer` | Workspace | Project ownership transferred. |
| `ws.hard_delete` | Workspace | Hard delete cleanup action. |
| `ws.artifact.create` | Workspace | File or artifact created. |
| `ws.artifact.update` | Workspace | File or artifact updated. |
| `ws.artifact.delete` | Workspace | File or artifact deleted. |
| `ws.artifact.download` | Workspace | File or artifact downloaded. |
| `ws.thread.create` | Workspace | Chat created. |
| `ws.thread.update` | Workspace | Chat updated. |
| `ws.thread.delete` | Workspace | Chat deleted. |
| `ws.interaction.create` | Workspace | Chat message or response created. |
| `ws.org.update` | Workspace | Organization settings updated. |
| `ws.user.create` | Workspace | User created. |
| `ws.user.enable` | Workspace | User enabled. |
| `ws.user.disable` | Workspace | User disabled. |
| `ws.user.role.update` | Workspace | User role updated. |
| `ws.integration.create` | Workspace | Integration created. |
| `ws.integration.configure` | Workspace | Integration configured. |
| `ws.integration.sync.complete` | Workspace | Integration sync completed. |
| `ws.integration.sync.failed` | Workspace | Integration sync failed. |
| `backoffice.account.create` | Backoffice | Account created. |
| `backoffice.account.login` | Backoffice | Account login. |
| `backoffice.account.pwd.reset` | Backoffice | Account password reset. |
| `backoffice.account.pwd.change` | Backoffice | Account password changed. |
| `backoffice.api_token.create` | Backoffice | API token created. |
| `backoffice.api_token.delete` | Backoffice | API token deleted. |
| `backoffice.gateway_logs.read` | Backoffice | Gateway-scoped logs retrieved. |
| `backoffice.logs.read` | Backoffice | Platform logs retrieved. |
| `security.auth.no_credentials` | Security | Authentication attempted without credentials. |
| `security.auth.failed_login` | Security | Login failed. |
| `security.auth.invalid_token` | Security | Invalid token used. |
| `security.auth.expired_token` | Security | Expired token used. |
| `security.auth.invalid_session` | Security | Invalid session used. |
| `security.auth.malformed_header` | Security | Malformed authentication header received. |
This event list covers documented application events. Helm-level logging configuration changes, such as changing retention or delivery destinations, should also be captured through customer change-management, GitOps, Kubernetes audit, or infrastructure audit controls.
## Log record schema
Each item returned by the log list endpoints is a `ZylonLogDTO`.
| Field | Notes |
| - | - |
| `id` | Log ID. |
| `gateway_id` | Gateway context when available. |
| `system_event` | Whether the backend marked the event as system-originated. |
| `request_id` | Request or generated correlation ID. |
| `event` | Event family. |
| `action` | Action name when available. |
| `organization_id` | Organization context when available. |
| `user_id` | Workspace user context when available. |
| `account_id`, `account_email` | Account context when available. |
| `token_id` | API token context when available. |
| `start_timestamp`, `end_timestamp` | ISO timestamps. |
| `ip_address` | Source IP when available. |
| `metadata` | Additional backend metadata. |
| `input_payload`, `payload` | Included only when requested. Sensitive request keys are masked before storage. |
| `error` | Error message or class name when logged. |
| `data` | Included only with `include=Data`; shape depends on `event`. |
Structured `data` can include workspace, HTTP, security, chat, embed, or ingest fields. Chat data can include model, token counts, request metadata, optional request messages, optional response, latency metrics, and `tools_used`.
Sensitive request keys such as passwords, tokens, API keys, secrets, credentials, cookies, and connection strings are masked before request input payloads are stored. Do not build export workflows that require recovering masked values from logs.
## List platform logs
```http theme={null}
GET /v1/platform/logs
```
Retrieves stored logs across gateway, workspace, backoffice, and security event families.
### Example request
```bash theme={null}
curl "https://{BASE_URL}/v1/platform/logs?event=zylon.workspace&action=ws.project.create&organizationId={ORG_ID}&page=0&page_size=50&total_count=true&include=Data,Payload" \
-H "Authorization: Bearer {API_TOKEN}"
```
### Example response
```json theme={null}
{
"data": [
{
"id": "01985a54-2f4d-7000-8001-4d7f7a6d9a10",
"gateway_id": "01985a50-6a8f-7000-8002-2149efc07b20",
"system_event": false,
"request_id": "req-01HZX9P6J8P5E2V0XQW7C9A2M4",
"event": "zylon.workspace",
"action": "ws.project.create",
"organization_id": "01985a4d-3c21-7000-8003-0e10dd81d901",
"user_id": "01985a4e-9811-7000-8004-d8f56e017c11",
"account_id": "01985a4f-a802-7000-8005-cd0c96f1a221",
"account_email": "operator@example.com",
"token_id": null,
"start_timestamp": "2026-05-19T09:21:43.120Z",
"end_timestamp": "2026-05-19T09:21:43.120Z",
"ip_address": "203.0.113.10",
"metadata": {},
"input_payload": {},
"payload": {
"project_id": "01985a55-d4e5-7000-8006-41ce955b14a0",
"name": "Customer Insights"
},
"error": null,
"data": {
"type": "workspace",
"id": "01985a54-2f4d-7000-8001-4d7f7a6d9a10",
"node_id": "01985a55-d4e5-7000-8006-41ce955b14a0",
"project_id": "01985a55-d4e5-7000-8006-41ce955b14a0"
}
}
],
"next_cursor": "01985a54-2f4d-7000-8001-4d7f7a6d9a10",
"previous_cursor": null,
"has_next_page": false,
"has_previous_page": false,
"total_count": 1
}
```
## List gateway logs
```http theme={null}
GET /v1/platform/gateway/{gatewayId}/logs
```
Retrieves stored logs for one gateway. The `{gatewayId}` path parameter is applied by the backend and overrides any `gatewayId` query parameter.
| Path parameter | Description |
| - | - |
| `gatewayId` | Gateway whose logs should be returned. |
### Example request
```bash theme={null}
curl "https://{BASE_URL}/v1/platform/gateway/{GATEWAY_ID}/logs?event=zylon.gateway.chat&tokenId={TOKEN_ID}&first=25&include=Data,ChatRequestMessages,ChatResponse" \
-H "Authorization: Bearer {API_TOKEN}"
```
## List AI usage logs
```http theme={null}
GET /v1/platform/usage
```
Returns a non-paginated list of limited AI usage records. This endpoint is optimized for usage charts. It returns data related to AI usage only: token consumption, tools used, and usage events for chat, embedding, and ingestion activity.
It does not return full log payloads, request prompts, full responses, security events, workspace audit records, or backoffice events. Use the log list endpoints with `include` when you need full stored log records.
### Usage filters
| Parameter | Description |
| - | - |
| `gatewayId` | Comma-separated gateway IDs. |
| `tokenId` | Match one API token. |
### Usage response schema
| Field | Notes |
| - | - |
| `id` | Log ID. |
| `gateway_id` | Gateway ID. |
| `token_id` | API token ID when available. |
| `start_timestamp` | ISO timestamp. |
| `event` | Usage event family. |
| `data` | Usage payload. Chat data includes request tokens, response tokens, and tools used. Ingest data includes artifact ID. Embed records currently return usage event metadata without an extra data payload. |
### Example request
```bash theme={null}
curl "https://{BASE_URL}/v1/platform/usage?gatewayId={GATEWAY_ID}&tokenId={TOKEN_ID}" \
-H "Authorization: Bearer {API_TOKEN}"
```
### Example response
```json theme={null}
[
{
"id": "01985a64-7e31-7000-8001-4f52b1dd2a89",
"gateway_id": "01985a50-6a8f-7000-8002-2149efc07b20",
"token_id": "01985a62-bbe7-7000-8007-828344268abc",
"start_timestamp": "2026-05-19T09:30:12.004Z",
"event": "zylon.gateway.chat",
"data": {
"type": "chat",
"id": "01985a64-7e31-7000-8001-4f52b1dd2a89",
"request_tokens": 14,
"response_tokens": 5,
"tools_used": []
}
}
]
```
## Errors and limitations
| Case | Result |
| - | - |
| Missing or invalid authentication | Request is rejected by authentication middleware. |
| Authenticated account without at least the `operator` role | Request is rejected by the permission check. |
| Invalid UUID, enum value, or pagination combination | Request is rejected before logs are returned. |
| Internal storage disabled | New logs are not persisted to Zylon log storage. Manual retrieval returns only already stored records. |
| Per-record modification or deletion | Not supported by the documented Logging API. Stored log retention is controlled by cleanup configuration. |
## Export chain of custody
When using these endpoints for a manual export, preserve evidence outside the response body:
* operator account or token identity;
* request timestamp, source IP, and request ID when available;
* exact URL filters, pagination values, and `include` values;
* number of records exported;
* incident, ticket, or legal hold reference.
Log retrieval calls are also logged as Backoffice actions: `/v1/platform/gateway/{gatewayId}/logs` emits `backoffice.gateway_logs.read`, and `/v1/platform/logs` emits `backoffice.logs.read`. Preserve those events together with the exported response when a review, incident, or legal hold requires evidence of who accessed log records.
## Related documentation
* [Backoffice API overview](/en/v1.57/developer-manual/build-with-zylon/backoffice-api/overview)
* [Auditability & AI Governance: Logging, Evidence, and SIEM Delivery](/en/v1.57/operator-manual/backoffice/log-delivery-storage)
* [Configuration: Log Delivery and Storage](/en/v1.57/operator-manual/configuration/features/log-delivery-storage)
# Overview
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/backoffice-api/overview
Backoffice API endpoints for operational and platform-level workflows.
The Backoffice API exposes platform-level endpoints for authorized operators and automation jobs. Use it for operational workflows that are outside the Workspace API, such as manually retrieving Zylon logs for investigation or export.
## Base URL
Backoffice endpoints are served from the platform root:
```http theme={null}
https://{BASE_URL}
```
Unlike Workspace API routes, Backoffice routes documented here do not use the `/api/v1/app` workspace prefix.
## Authentication and permissions
Backoffice API requests require an account token or account session with at least the `operator` role.
```bash theme={null}
-H "Authorization: Bearer {API_TOKEN}"
```
Workspace-only tokens are not enough for Backoffice endpoints.
## Available sections
Retrieve stored platform, gateway, security, workspace, and AI usage logs.
For governance, auditability, evidence preservation, and retention guidance, see [Auditability & AI Governance: Logging, Evidence, and SIEM Delivery](/en/v1.57/operator-manual/backoffice/log-delivery-storage).
# Database Query tool
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/tools/built-in/database-query-tool
Query a SQL database from natural language.
Use Database Query when you want the assistant to translate natural language into SQL over a configured database connection.
## Prerequisites
* An API token. See [Backoffice Developer Console](/en/v1.57/developer-manual/get-started/developer-console).
* A database connection string you can share with Zylon.
## Requirements
* Tool spec: `{ "name": "database_query", "type": "database_query_v1" }`
* `tool_context`: one `sql_database` context with `connection_string`
## Basic request and response
This example validates a request that enables database query. For validation, it sets `tool_choice` to `none` so the validator doesn’t try to connect.
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/messages/validate" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"model": "default",
"max_tokens": 128,
"messages": [
{ "role": "user", "content": "What were total Q1 subscriptions by plan?" }
],
"tools": [
{ "name": "database_query", "type": "database_query_v1" }
],
"tool_choice": { "type": "none" },
"tool_context": [
{
"type": "sql_database",
"connection_string": "postgresql://{username}:{password}@db.example.com:5432/analytics",
"schemas": ["public"],
"ssl": true
}
]
}'
```
Example response:
```json theme={null}
{ "valid": true, "errors": null }
```
To run the request, send the same body to `POST /messages` and set `tool_choice` to `{ \"type\": \"auto\" }`.
## Tips
* Use a read-only database user.
* Limit schemas to reduce inspection time.
## Next steps
* Learn how messages return tool blocks: [Messages](/en/v1.57/developer-manual/build-with-zylon/working-with-messages)
# Semantic Search tool
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/tools/built-in/semantic-search-tool
Search your ingested artifacts for relevant chunks during a message.
Use Semantic Search when you want the assistant to retrieve information from previously ingested artifacts (documents, notes, PDFs, HTML, and more).
## Prerequisites
* An API token. See [Backoffice Developer Console](/en/v1.57/developer-manual/get-started/developer-console).
* Ingested artifacts to search (see [Artifacts](/en/v1.57/developer-manual/build-with-zylon/working-with-artifacts)).
## Requirements
* Tool spec: `{ "name": "semantic_search", "type": "semantic_search_v1" }`
* `tool_context`: at least one `ingested_artifact` with a `context_filter`
## Basic request and response
This example validates a request that enables semantic search over a collection:
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/messages/validate" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"model": "default",
"max_tokens": 128,
"messages": [
{ "role": "user", "content": "What shipped in the latest billing dashboard release?" }
],
"tools": [
{ "name": "semantic_search", "type": "semantic_search_v1" }
],
"tool_choice": { "type": "auto" },
"tool_context": [
{
"type": "ingested_artifact",
"context_filter": {
"collection": "{collectionID}"
}
}
]
}'
```
Example response:
```json theme={null}
{ "valid": true, "errors": null }
```
To run the request, send the same body to `POST /messages`.
## Tips
* Keep `tool_context` narrow (use a single collection and the smallest set of artifacts you need).
* If you’re not getting relevant results, ingest cleaner source text (or split large documents into smaller artifacts).
## Next steps
* Ingest and manage artifacts: [Artifacts](/en/v1.57/developer-manual/build-with-zylon/working-with-artifacts)
* Learn how messages return tool blocks: [Messages](/en/v1.57/developer-manual/build-with-zylon/working-with-messages)
# Tabular Analysis tool
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/tools/built-in/tabular-analysis-tool
Analyze ingested tabular artifacts during a message.
Use Tabular Analysis when you want the assistant to perform calculations over tabular data (CSV, TSV, or tables extracted from documents).
## Prerequisites
* An API token. See [Backoffice Developer Console](/en/v1.57/developer-manual/get-started/developer-console).
* Ingested tabular artifacts to analyze.
## Requirements
* Tool spec: `{ "name": "tabular_analysis", "type": "tabular_analysis_v1" }`
* `tool_context`: at least one `ingested_artifact` with a `context_filter`
## Basic request and response
This example validates a request that enables tabular analysis over a collection:
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/messages/validate" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"model": "default",
"max_tokens": 128,
"messages": [
{ "role": "user", "content": "What is the average of the Q1 revenue column?" }
],
"tools": [
{ "name": "tabular_analysis", "type": "tabular_analysis_v1" }
],
"tool_choice": { "type": "auto" },
"tool_context": [
{
"type": "ingested_artifact",
"context_filter": {
"collection": "{collectionID}"
}
}
]
}'
```
Example response:
```json theme={null}
{ "valid": true, "errors": null }
```
To run the request, send the same body to `POST /messages`.
## Tips
* Ensure the artifact content is a clean table (CSV/TSV is best).
* Keep the table small enough for quick analysis.
## Next steps
* Ingest and manage artifacts: [Artifacts](/en/v1.57/developer-manual/build-with-zylon/working-with-artifacts)
* Learn how messages return tool blocks: [Messages](/en/v1.57/developer-manual/build-with-zylon/working-with-messages)
# Web Fetch tool
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/tools/built-in/web-fetch-tool
Fetch and extract a URL mentioned in the message.
Use Web Fetch when you need the assistant to retrieve content from a URL.
## Prerequisites
* An API token. See [Backoffice Developer Console](/en/v1.57/developer-manual/get-started/developer-console).
## Requirements
* Tool spec: `{ "name": "web_extract", "type": "web_extract_v1" }`
* No `tool_context` required
## Basic request and response
This example validates a request that enables the web fetch tool:
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/messages/validate" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"model": "default",
"max_tokens": 64,
"messages": [
{ "role": "user", "content": "Summarize https://example.com/" }
],
"tools": [
{ "name": "web_extract", "type": "web_extract_v1" }
],
"tool_choice": { "type": "auto" }
}'
```
Example response:
```json theme={null}
{ "valid": true, "errors": null }
```
To run the request, send the same body to `POST /messages`.
## Tips
* The URL must appear in the user message.
* Keep the prompt concise to reduce extraction time.
## Next steps
* Learn how messages return tool blocks: [Messages](/en/v1.57/developer-manual/build-with-zylon/working-with-messages)
# Web Search tool
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/tools/built-in/web-search-tool
Search the web from a natural language query.
Use Web Search when you need the assistant to run a quick web query and return results.
## Prerequisites
* An API token. See [Backoffice Developer Console](/en/v1.57/developer-manual/get-started/developer-console).
## Requirements
* Tool spec: `{ "name": "web_search", "type": "web_search_v1" }`
* No `tool_context` required
## Basic request and response
This example validates a request that enables the web search tool:
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/messages/validate" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"model": "default",
"max_tokens": 64,
"messages": [
{ "role": "user", "content": "Find recent updates about the EU AI Act." }
],
"tools": [
{ "name": "web_search", "type": "web_search_v1" }
],
"tool_choice": { "type": "auto" }
}'
```
Example response:
```json theme={null}
{ "valid": true, "errors": null }
```
To run the request, send the same body to `POST /messages`.
## Tips
* Use a focused query to reduce noisy results.
* Combine with a system prompt to control summarization style.
## Next steps
* Learn how messages return tool blocks: [Messages](/en/v1.57/developer-manual/build-with-zylon/working-with-messages)
# Custom tools
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/tools/custom/custom-tools
Define your own tools using JSON Schema.
Custom tools let you define a tool interface (name + JSON schema) and let the assistant choose when to call it. When it calls your tool, it returns a `tool_use` content block with structured `input`.
## Prerequisites
* An API token. See [Backoffice Developer Console](/en/v1.57/developer-manual/get-started/developer-console).
## Requirements
In the `tools` array, provide:
* `name`: unique tool name
* `description`: what the tool does
* `inputSchema`: JSON Schema describing the tool input
## Basic request and response
This example validates a request that defines a tiny calculator tool and forces its use.
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/messages/validate" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"model": "default",
"max_tokens": 64,
"messages": [
{ "role": "user", "content": "Add 5 and 7." }
],
"tools": [
{
"name": "simple_calculator",
"description": "Add two numbers.",
"inputSchema": {
"type": "object",
"additionalProperties": false,
"properties": {
"a": { "type": "number" },
"b": { "type": "number" }
},
"required": ["a", "b"]
}
}
],
"tool_choice": { "type": "tool", "name": "simple_calculator" }
}'
```
Example response:
```json theme={null}
{ "valid": true, "errors": null }
```
To run the request, send the same body to `POST /messages`. When the assistant returns a `tool_use` block, execute your tool and include a `tool_result` block in the next message.
# Overview
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/tools/introduction-to-tools
Enable built-in and custom tools in Messages.
Tools let the assistant run targeted operations (like searching artifacts, analyzing tabular data, or extracting a web page) as part of a message response.
You enable tools by adding three fields to a `POST /messages` request:
| Field | Purpose |
| - | - |
| `tools` | Which tools are allowed. |
| `tool_choice` | How the assistant should choose tools (`auto`, force a specific tool, or `none`). |
| `tool_context` | Optional context artifacts (documents or database connections). |
## Prerequisites
* An API token. See [Backoffice Developer Console](/en/v1.57/developer-manual/get-started/developer-console).
* Your Zylon hostname (replace `{BASE_URL}` in the examples).
## Basic request and response
When you’re iterating on tool configuration, start with `POST /messages/validate` to validate your request body without running a model.
This example enables the **web fetch** tool:
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/messages/validate" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"model": "default",
"max_tokens": 64,
"messages": [
{ "role": "user", "content": "Summarize: https://example.com/" }
],
"tools": [
{ "name": "web_extract", "type": "web_extract_v1" }
],
"tool_choice": { "type": "auto" }
}'
```
```json theme={null}
{ "valid": true, "errors": null }
```
To actually run the request, send the same body to `POST /messages`.
## Built-in tools
Zylon includes a set of built-in tools you can enable by name + type:
| Tool type | What it does | Requires `tool_context` |
| - | - | - |
| `semantic_search_v1` | Search ingested artifacts | Yes (`ingested_artifact`) |
| `tabular_analysis_v1` | Analyze tabular artifacts | Yes (`ingested_artifact`) |
| `web_extract_v1` | Fetch and extract a URL mentioned in the message | No |
| `web_search_v1` | Search the web from a natural language query | No |
| `database_query_v1` | Query a SQL database from natural language | Yes (`sql_database`) |
Guides:
* [Semantic Search tool](/en/v1.57/developer-manual/build-with-zylon/tools/built-in/semantic-search-tool)
* [Tabular Analysis tool](/en/v1.57/developer-manual/build-with-zylon/tools/built-in/tabular-analysis-tool)
* [Web Fetch tool](/en/v1.57/developer-manual/build-with-zylon/tools/built-in/web-fetch-tool)
* [Web Search tool](/en/v1.57/developer-manual/build-with-zylon/tools/built-in/web-search-tool)
* [Database Query tool](/en/v1.57/developer-manual/build-with-zylon/tools/built-in/database-query-tool)
## Custom tools
Custom tools let you define your own tool interface using JSON Schema. When the assistant chooses your tool, it returns a `tool_use` content block with structured `input`.
See: [Custom tools](/en/v1.57/developer-manual/build-with-zylon/tools/custom/custom-tools)
## Common mistakes
* **Using the wrong field name**: tool schemas use `inputSchema` (not `input_schema`).
* **Missing tool context**: `semantic_search_v1`, `tabular_analysis_v1`, and `database_query_v1` need `tool_context`.
* **Forgetting auth**: include `Authorization: Bearer ...` on every request.
## Next steps
* Learn the Messages request format: [Messages](/en/v1.57/developer-manual/build-with-zylon/working-with-messages)
* Ingest content for retrieval and analysis: [Artifacts](/en/v1.57/developer-manual/build-with-zylon/working-with-artifacts)
# Artifacts
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/working-with-artifacts
Create and ingest ZylonGPT artifacts for retrieval and context.
An **artifact** is a piece of information (or tool-ready resource) you ingest into Zylon so it can be used as context for queries and operations. Artifacts live inside a **collection**, and each artifact has a stable `artifact` ID.
Artifacts can be created from:
| Type | Input | Notes |
| - | - | - |
| **Text** | Raw string | Provide content directly. |
| **File** | Base64 bytes | For files like `.txt` or `.pdf`. |
| **URI** | URL | Zylon fetches and ingests the content. |
## Prerequisites
* An API token. See [Backoffice Developer Console](/en/v1.57/developer-manual/get-started/developer-console).
* Your Zylon hostname (replace `{BASE_URL}` in the examples).
## Basic request and response
Use `POST /artifacts/ingest` when you want the ingest to complete in the same request.
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/ingest" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"collection": "{collectionID}",
"artifact": "{artifactID}",
"input": {
"type": "text",
"value": "Release notes: Shipped billing dashboard and fixed three bugs."
},
"metadata": {
"file_name": "release_notes.txt",
"source": "docs"
}
}'
```
```json theme={null}
{
"object": "list",
"model": "private-gpt",
"data": [
{
"object": "ingest.document",
"artifact": "docs_text_artifact_sync",
"doc_metadata": {
"file_name": "release_notes.txt",
"source": "docs",
"headers": [],
"artifact_id": "docs_text_artifact_sync",
"collection": "019c7569-f1f3-74da-8017-35d4a11f93ca",
"llm_model": "default",
"embed_model": "default",
"hash": "faf6da679814136cb7cef94532397948cd2cd303b25f91a527af53227e9da99d"
}
}
]
}
```
## Async ingest
Use `POST /artifacts/ingest/async` for larger payloads or when ingest may take longer. The payload is the same as sync ingest, wrapped in `ingest_body`, and the response returns a `task_id` you can poll.
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/ingest/async" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"ingest_body": {
"collection": "{collectionID}",
"artifact": "{artifactID}",
"input": {
"type": "text",
"value": "Release notes: We shipped a new billing dashboard and fixed three bugs."
},
"metadata": {
"file_name": "release_notes.txt",
"source": "docs"
}
}
}'
```
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/ingest/async" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"ingest_body": {
"collection": "{collectionID}",
"artifact": "{artifactID}",
"input": {
"type": "file",
"value": "SGVsbG8gZnJvbSBmaWxlIGFydGlmYWN0Lgo="
},
"metadata": {
"file_name": "onboarding_checklist.txt",
"source": "docs"
}
}
}'
```
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/ingest/async" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"ingest_body": {
"collection": "{collectionID}",
"artifact": "{artifactID}",
"input": {
"type": "uri",
"value": "https://example.com/"
},
"metadata": {
"file_name": "example.html",
"source": "docs"
}
}
}'
```
```json theme={null}
{ "task_id": "f04e0709-131a-4a9d-b884-78872a4e63d7" }
```
Check task status:
```bash theme={null}
curl "https://{BASE_URL}/api/gpt/v1/artifacts/ingest/async/{task_id}" \
-H "Authorization: Bearer {API_TOKEN}"
```
```json theme={null}
{
"task_id": "f04e0709-131a-4a9d-b884-78872a4e63d7",
"task_status": "PENDING",
"task_result": null
}
```
## Listing ingested artifacts
```bash theme={null}
curl "https://{BASE_URL}/api/gpt/v1/artifacts/list?collection={collectionID}" \
-H "Authorization: Bearer {API_TOKEN}"
```
```json theme={null}
{
"object": "list",
"model": "private-gpt",
"data": [
{
"object": "ingest.document",
"artifact": "docs_file_artifact",
"doc_metadata": {
"file_name": "docs_file_artifact.txt",
"artifact_id": "docs_file_artifact",
"collection": "019c7569-f1f3-74da-8017-35d4a11f93ca"
}
}
]
}
```
## Retrieving content
### Full content
Use `POST /artifacts/content` to fetch complete document text:
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/content" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"context_filter": {
"collection": "{collectionID}"
}
}'
```
```json theme={null}
{
"data": [
{
"artifact_id": "docs_file_artifact",
"content": "Hello from file artifact.\n\n"
}
]
}
```
### Chunked content (chat-optimized)
Use `POST /artifacts/chunked-content` to retrieve content split into chat-friendly blocks:
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/chunked-content" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"context_filter": {
"collection": "{collectionID}"
},
"max_tokens": 50
}'
```
```json theme={null}
{
"data": [
{
"artifact_id": "docs_file_artifact",
"content": [
{ "type": "source", "sources": [{ "object": "context.chunk", "id": "c5f20f0f-56e6-44e0-99e8-0d4ff4bb87eb" }] },
{ "type": "text", "text": "**Context Information**:\nBelow is important information..." }
]
}
]
}
```
## Deleting artifacts
Delete (sync):
```bash theme={null}
curl -i -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/delete" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"collection": "{collectionID}",
"artifact": "{artifactID}"
}'
```
```text theme={null}
HTTP/2 200
null
```
Delete (async):
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/delete/async" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"delete_body": {
"collection": "{collectionID}",
"artifact": "{artifactID}"
}
}'
```
```json theme={null}
{ "task_id": "2d48e74f-3eff-474e-b338-a931390ac218" }
```
Check task status:
```bash theme={null}
curl "https://{BASE_URL}/api/gpt/v1/artifacts/delete/async/{task_id}" \
-H "Authorization: Bearer {API_TOKEN}"
```
```json theme={null}
{
"task_id": "2d48e74f-3eff-474e-b338-a931390ac218",
"task_status": "PENDING",
"task_result": null
}
```
Keep polling until `task_status` becomes `"SUCCESS"` or `"FAILURE"`.
If deletion fails while an index is still being populated, retry after a short delay.
## Errors and edge cases
* **401/403**: missing token or insufficient permissions.
* **404**: collection or artifact not found.
* **409**: ingest/delete task already in progress.
* **413**: input too large for a single ingest.
* **422**: invalid payload shape.
* **Async failures**: when `task_status` becomes `FAILURE`, check `task_result` (for example `routing_key_error: "ingest.failed"` or `delete.failed`) and retry after fixing the input.
# Messages
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/working-with-messages
Message requests with sync, streaming, and async patterns.
Messages is the core of ZylonGPT. You send a conversation history, and Zylon returns the next assistant message as a **list of content blocks** (text, tool calls, tool results, and more).
## Prerequisites
* An API token. See [Backoffice Developer Console](/en/v1.57/developer-manual/get-started/developer-console).
* Your Zylon hostname (replace `{BASE_URL}` in the examples).
## Basic request and response
Send one user message and get back one assistant message.
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/messages" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"model": "default",
"max_tokens": 32,
"temperature": 0,
"messages": [
{ "role": "user", "content": "Write a one-sentence status update about deploying a billing dashboard and fixing three bugs." }
]
}'
```
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/messages" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"model": "default",
"max_tokens": 32,
"temperature": 0,
"messages": [
{
"role": "user",
"content": [
{ "type": "text", "text": "Write a one-sentence status update about deploying a billing dashboard and fixing three bugs." }
]
}
]
}'
```
```json theme={null}
{
"id": "msg_abf981cf3f1c449eacb7a85c064ca505",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"start_timestamp": "2026-02-06T13:23:16.876744Z",
"stop_timestamp": "2026-02-06T13:23:16.975362Z",
"text": "Deployed the new billing dashboard and resolved three bugs successfully."
}
],
"model": "private-gpt",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 95,
"output_tokens": 16
}
}
```
To render plain text, concatenate the `text` values from any blocks where `type` is `"text"`.
## Messages shape
At minimum, send:
| Field | Required | Description |
| - | - | - |
| `model` | Yes | Model name to use (commonly `"default"`). |
| `messages` | Yes | Conversation history. |
| `max_tokens` | Yes | Maximum tokens to generate. |
Each message has:
| Field | Description |
| - | - |
| `role` | `"user"` or `"assistant"`. |
| `content` | A string, or an array of content blocks. |
## Validate a request
Use `/messages/validate` to check payload shape before sending a real request. It returns `valid: true` or a list of validation errors.
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/messages/validate" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"model": "default",
"max_tokens": 32,
"messages": [
{ "role": "user", "content": "Validate this payload." }
]
}'
```
Example response:
```json theme={null}
{ "valid": true, "errors": null }
```
## Multi-turn conversations
To continue a conversation, include the prior turns in `messages`:
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/messages" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"model": "default",
"max_tokens": 16,
"temperature": 0,
"messages": [
{ "role": "user", "content": "My name is Ada." },
{ "role": "assistant", "content": "Nice to meet you." },
{ "role": "user", "content": "What is my name? Reply with only the name, no punctuation." }
]
}'
```
```json theme={null}
{
"id": "msg_9b14c8fd514741d29a0dff8996ca9213",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"start_timestamp": "2026-02-06T10:34:12.924887Z",
"stop_timestamp": "2026-02-06T10:34:12.974785Z",
"text": "Ada"
}
],
"model": "private-gpt",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": { "input_tokens": 135, "output_tokens": 2 }
}
```
## System prompts
Use the top-level `system` field to control assistant behavior (instead of a `"system"` role message):
Prefer the top-level system field for system instructions so they are applied consistently across the whole request.
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/messages" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"model": "default",
"max_tokens": 8,
"temperature": 0,
"system": { "text": "You are a support agent. Reply with only a short ticket title.", "use_default_prompt": false },
"messages": [
{ "role": "user", "content": "The login button on mobile does not work." }
]
}'
```
```json theme={null}
{
"id": "msg_4e328dc4baeb42b8a18dc0c4abd89468",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"start_timestamp": "2026-02-06T13:37:36.368426Z",
"stop_timestamp": "2026-02-06T13:37:36.446733Z",
"text": "Mobile login button not working"
}
],
"model": "private-gpt",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": { "input_tokens": 100, "output_tokens": 6 }
}
```
## Structured JSON output (json\_schema)
If you need machine-readable output, set `response_format.type` to `json_schema` and provide a schema. Zylon returns JSON as text in a `text` content block.
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/messages" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"model": "default",
"max_tokens": 128,
"response_format": {
"type": "json_schema",
"json_schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"status": { "type": "string" },
"next_step": { "type": "string" }
},
"required": ["status", "next_step"]
}
},
"system": { "text": "Return ONLY valid JSON.", "use_default_prompt": false },
"messages": [
{ "role": "user", "content": "We deployed the billing dashboard. Return a status and the next step." }
]
}'
```
```json theme={null}
{
"id": "msg_eaf35004b4654234be5e767ea09e72e6",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"start_timestamp": "2026-02-06T13:39:44.864978Z",
"stop_timestamp": "2026-02-06T13:39:45.412991Z",
"text": "{\"status\":\"success\",\"next_step\":\"Monitor adoption and collect feedback.\"}"
}
],
"model": "private-gpt",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": { "input_tokens": 98, "output_tokens": 16 }
}
```
## Streaming (SSE)
Set `stream: true` to receive a `text/event-stream` response containing events like `content_block_delta` (token deltas).
```bash theme={null}
curl -N -X POST "https://{BASE_URL}/api/gpt/v1/messages" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{
"model": "default",
"stream": true,
"max_tokens": 32,
"messages": [
{ "role": "user", "content": "Give a three-word tagline for a productivity app." }
]
}'
```
```text theme={null}
event: message_start
data: {"type":"message_start","message":{"id":"msg_b55d29718361410bad4f80f8f67c6b72","type":"message","role":"assistant","content":[],"model":"private-gpt","usage":{}}}
event: content_block_start
data: {"type":"content_block_start","index":0,"block_id":"block_019c331ac11375cea03f7e0fb7a2a044","content_block":{"type":"text","start_timestamp":"2026-02-06T13:18:37.331257Z","text":""}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"block_id":"block_019c331ac11375cea03f7e0fb7a2a044","delta":{"type":"text_delta","text":"Focus"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"block_id":"block_019c331ac11375cea03f7e0fb7a2a044","delta":{"type":"text_delta","text":" fast daily"}}
event: content_block_stop
data: {"type":"content_block_stop","stop_timestamp":"2026-02-06T13:18:37.417617Z","index":0,"block_id":"block_019c331ac11375cea03f7e0fb7a2a044"}
event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"input_tokens":90,"output_tokens":3}}
event: message_stop
data: {"type":"message_stop"}
```
## Async messages
Async messages use the **same request body** as sync messages—you just call a different endpoint. The main difference is the **response shape**: sync returns a full message, async returns a `message_id` you can stream or poll later.
```json theme={null}
{
"id": "msg_abf981cf3f1c449eacb7a85c064ca505",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"start_timestamp": "2026-02-06T13:23:16.876744Z",
"stop_timestamp": "2026-02-06T13:23:16.975362Z",
"text": "Deployed the new billing dashboard and resolved three bugs successfully."
}
],
"model": "private-gpt",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 95,
"output_tokens": 16
}
}
```
```json theme={null}
{
"message_id": "1cc8ed5e-fc7a-45e1-baf4-0b916ed32290",
"status": "pending",
"message": "Request initiated successfully"
}
```
### Start an async message
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/messages/async" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"model": "default",
"max_tokens": 32,
"messages": [
{ "role": "user", "content": "Say only: async ok" }
]
}'
```
### Stream or poll status
Stream events:
```bash theme={null}
curl -N "https://{BASE_URL}/api/gpt/v1/messages/async/{message_id}/stream" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Accept: text/event-stream"
```
Poll status:
```bash theme={null}
curl "https://{BASE_URL}/api/gpt/v1/messages/async/{message_id}/status" \
-H "Authorization: Bearer {API_TOKEN}"
```
### Cancel or delete
* Cancel: `POST /messages/async/{message_id}/cancel`
* Delete: `DELETE /messages/async/{message_id}/delete`
## Common mistakes
* **Wrong method**: `/messages` is `POST`, not `GET`.
* **Missing auth header**: include `Authorization: Bearer ...`.
* **Wrong base URL**: use `https://{BASE_URL}/api/gpt/v1/`.
* **Invalid request body**: use `POST /messages/validate` to catch schema mistakes early.
* **Unexpected stops or errors**: see [Handling stop reasons](/en/v1.57/developer-manual/build-with-zylon/zylon-gpt-api/handling-stop-reasons) for causes and fixes.
## Next steps
Let Zylon use built-in and custom tools during a message.
Ingest text, files, or URIs into collections for retrieval.
# Auth
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/workspace-api/authentication/auth
Log in and end sessions for Workspace API access.
Use these endpoints to exchange credentials for a session and log out. For SSO login redirects (Google/Microsoft) and integration OAuth, see [OpenID & OAuth](/en/v1.57/developer-manual/build-with-zylon/workspace-api/authentication/openid).
## Account creation
Use `POST /api/v1/auth/register` to create a new credentials-based account.
To use that account in Workspace, complete one of these operations:
* Create a workspace user with the account ID in [Users - Create a user](/en/v1.57/developer-manual/build-with-zylon/workspace-api/users/user).
* Join directly to an organization through `POST /api/v1/account/organization/{orgId}/join`.
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/auth/register" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"name": "Sasha Patel",
"email": "sasha@example.com",
"password": "{password}",
"roles": ["Admin"]
}'
```
| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | No | Account display name. |
| `email` | string | Yes | Account email. |
| `password` | string | Yes | Credentials password. |
| `roles` | string\[] | Yes | Account-level roles. At least one valid role is required. |
```json theme={null}
{
"id": "acct_6c8a1f3b2d4e5f7a",
"state": "Active",
"email": "sasha@example.com",
"name": "Sasha Patel",
"given_name": null,
"family_name": null,
"profile_picture": null,
"provider": "Credentials",
"users": null,
"roles": ["Admin"],
"created_at": "2026-02-08T14:12:45Z",
"updated_at": "2026-02-08T14:12:45Z"
}
```
## Log in with credentials
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/auth/login" \
-H "Content-Type: application/json" \
-d '{
"email": "{username}",
"password": "{password}"
}'
```
```json theme={null}
"ok"
```
Successful login creates an account session. When LDAP is enabled, the server first tries LDAP authentication and then falls back to local credentials.
## Log out
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/auth/logout" \
-H "Authorization: Bearer {API_TOKEN}"
```
```json theme={null}
"ok"
```
## Manage API tokens
Use these endpoints to manage API tokens for the authenticated account. Token secrets are returned only when a token is created; after that, list responses include metadata and the token hash.
### List tokens
| Query parameter | Type | Required | Description |
| - | - | - | - |
| `page_size` | integer | No | Maximum number of tokens to return. |
| `after` / `before` | string | No | Cursor pagination controls when available. |
| `gateway_id` | string | No | Filter tokens by gateway ID. |
```bash theme={null}
curl "https://{BASE_URL}/api/v1/account/token?page_size=20" \
-H "Authorization: Bearer {API_TOKEN}"
```
```json theme={null}
{
"data": [
{
"id": "tok_7f1a9c2d4b6e",
"name": "workspace-sync",
"token": null,
"scopes": ["Workspace.ReadWrite.All"],
"gateway_id": null,
"hashed_token": "{token_hash}",
"token_email": "workspace-sync@example.com",
"last_used_at": "2026-05-10T08:31:12Z",
"created_at": "2026-05-01T10:00:00Z",
"valid_until": "2026-12-31T23:59:59Z"
}
],
"next_cursor": null,
"previous_cursor": null,
"has_next_page": false,
"has_previous_page": false,
"total_count": 1
}
```
### Create a token
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/account/token" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"name": "workspace-sync",
"revoke_existing": false,
"valid_until": "2026-12-31T23:59:59Z",
"scopes": ["Workspace.ReadWrite.All"]
}'
```
| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | No | Human-readable token name. |
| `revoke_existing` | boolean | No | When `true`, revokes existing tokens according to server policy. Defaults to `false`. |
| `valid_until` | timestamp | No | Expiration timestamp. Use `null` or omit for no explicit expiration. |
| `scopes` | string\[] | No | Allowed values: `ReadWrite.All`, `Workspace.ReadWrite.All`, `PrivateGPT.ReadWrite.All`. Defaults to `Workspace.ReadWrite.All`. |
| `gateway_id` | string | No | Gateway ID when creating a gateway-scoped token. |
```json theme={null}
{
"id": "tok_7f1a9c2d4b6e",
"name": "workspace-sync",
"token": "{API_TOKEN}",
"scopes": ["Workspace.ReadWrite.All"],
"gateway_id": null,
"hashed_token": "{token_hash}",
"token_email": "workspace-sync@example.com",
"last_used_at": null,
"created_at": "2026-05-01T10:00:00Z",
"valid_until": "2026-12-31T23:59:59Z"
}
```
Copy the `token` value immediately. It is returned only once and cannot be recovered later.
### Delete a token
Delete uses the stored token hash, not the clear token secret.
```bash theme={null}
curl -X DELETE "https://{BASE_URL}/api/v1/account/token/{token_hash}" \
-H "Authorization: Bearer {API_TOKEN}"
```
```json theme={null}
"Token deleted"
```
## Errors and edge cases
* **401/403**: missing or invalid API token.
* **429**: too many login attempts.
* **400**: register payload missing required account roles, email, or password.
# OpenID & OAuth
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/workspace-api/authentication/openid
Start SSO logins and integration OAuth flows for Confluence and SharePoint.
Use these endpoints to initiate OAuth/OpenID flows. Login endpoints are browser-oriented and return redirects; callback endpoints receive the provider response.
> Integrations must be enabled before you use their OAuth endpoints. See the operator guides for [Confluence](/en/v1.57/operator-manual/knowledge-base/confluence) and [SharePoint](/en/v1.57/operator-manual/knowledge-base/sharepoint).
## Basic request and response
Start a login flow by calling a provider login endpoint and following the redirect.
### User SSO login redirects
```bash theme={null}
curl -i "https://{BASE_URL}/api/v1/auth/google/login"
```
```text theme={null}
HTTP/1.1 302 Found
Location: https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...
```
```bash theme={null}
curl -i "https://{BASE_URL}/api/v1/auth/microsoft/login"
```
```text theme={null}
HTTP/1.1 302 Found
Location: https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=...&redirect_uri=...
```
### Integration OAuth login redirects
```bash theme={null}
curl -i "https://{BASE_URL}/api/v1/app/integration/confluence/login"
```
```text theme={null}
HTTP/1.1 302 Found
Location: https://auth.atlassian.com/authorize?client_id=...&redirect_uri=...
```
```bash theme={null}
curl -i "https://{BASE_URL}/api/v1/app/integration/sharepoint/login"
```
```text theme={null}
HTTP/1.1 302 Found
Location: https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=...&redirect_uri=...
```
### Login with a specific integration instance
```bash theme={null}
curl -i "https://{BASE_URL}/api/v1/app/integration/confluence/{integrationID}/login"
```
```text theme={null}
HTTP/1.1 302 Found
Location: https://auth.atlassian.com/authorize?client_id=...&state=conf_8a7b6c5d4e3f2a1b
```
```bash theme={null}
curl -i "https://{BASE_URL}/api/v1/app/integration/sharepoint/{integrationID}/login"
```
```text theme={null}
HTTP/1.1 302 Found
Location: https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=...&state=sp_1c2d3e4f5a6b7c8d
```
### Refresh an integration token
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/integration/confluence/{integrationID}/refresh_token" \
-H "Authorization: Bearer {API_TOKEN}"
```
```json theme={null}
"ok"
```
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/integration/sharepoint/{integrationID}/refresh_token" \
-H "Authorization: Bearer {API_TOKEN}"
```
```json theme={null}
"ok"
```
### Callback endpoints
| Type | Name | Required | Notes |
| - | - | - | - |
| Query | `code` | Yes | OAuth authorization code. |
| Query | `state` | Yes | OAuth state value returned by the provider. |
```bash theme={null}
curl -i "https://{BASE_URL}/api/v1/auth/microsoft/callback?code=...&state=..."
```
```text theme={null}
HTTP/1.1 302 Found
Location: https://{BASE_URL}/app/login/success
```
| Type | Name | Required | Notes |
| - | - | - | - |
| Query | `code` | Yes | OAuth authorization code. |
| Query | `state` | Yes | OAuth state value returned by the provider. |
```bash theme={null}
curl -i "https://{BASE_URL}/api/v1/app/integration/confluence/callback?code=...&state=..."
```
```text theme={null}
HTTP/1.1 302 Found
Location: https://{BASE_URL}/app/integrations/confluence
```
| Type | Name | Required | Notes |
| - | - | - | - |
| Query | `code` | Yes | OAuth authorization code. |
| Query | `state` | Yes | OAuth state value returned by the provider. |
```bash theme={null}
curl -i "https://{BASE_URL}/api/v1/app/integration/sharepoint/callback?code=...&state=..."
```
```text theme={null}
HTTP/1.1 302 Found
Location: https://{BASE_URL}/app/integrations/sharepoint
```
## Errors and edge cases
* **302 redirect**: expected for login and callback routes.
* **401/403**: token missing for refresh.
* **404**: integration ID not found.
# Chats
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/workspace-api/chats/threads
Threads, interactions, and one-shot chat endpoints.
Chats in the Workspace API are organized around **threads** and **interactions**:
| Concept | Meaning |
| - | - |
| **Thread** | A conversation container within a project. |
| **Interaction** | A single exchange inside a thread. |
| **Chat** | A one‑shot request that does **not** create a thread. |
Use threads when you want history and follow‑ups. Use interactions to send a new turn into a thread. Use the chat endpoint for single‑turn requests.
## Basic request and response
Create a thread interaction with `POST /api/v1/app/thread/{threadId}/interaction`.
| Type | Name | Required | Notes |
| - | - | - | - |
| Path | `threadID` | Yes | Thread identifier. |
| Body | `thread_id` | Yes | Thread identifier. |
| Body | `pgpt` | Yes | Chat request body. |
| Body | `artifact_ids` | No | Artifact IDs to use as context. |
| Body | `all_artifacts` | No | Include all available artifacts when `true`. |
| Body | `agent` | No | Agent preset to use. |
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/thread/{threadID}/interaction" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"thread_id": "{threadID}",
"artifact_ids": ["{artifactID}"],
"all_artifacts": false,
"agent": "Default",
"pgpt": {
"messages": [
{
"role": "user",
"content": [
{ "type": "text", "text": "Summarize the artifact in three bullets." }
]
}
],
"max_tokens": 120,
"temperature": 0.2
}
}'
```
```json theme={null}
{
"id": "inter_5a7b9c1d3e5f7a9b",
"project_id": "proj_7a5c3e1b9d2f4a6c",
"thread_id": "thread_3f2a1c4d5b6e7f8a",
"state": "Completed",
"artifact_ids": ["artifact_2b4d6f8a1c3e5a7b"],
"all_artifacts": false,
"user_input": {
"role": "user",
"content": [
{ "type": "text", "text": "Summarize the artifact in three bullets." }
]
},
"assistant_output": {
"id": "msg_3d2c1b4a5f6e7d8c",
"created": 1739036500,
"model": "default",
"stop_reason": "end_turn",
"content": [
{ "type": "text", "text": "• Ticket volume rose 12% week-over-week\n• Billing issues drove 38% of cases\n• Priority bugs were resolved within 48 hours" }
],
"usage": { "input_tokens": 180, "output_tokens": 52 }
},
"created_at": "2026-02-08T14:41:10Z"
}
```
## Adding media to the chat
If the selected model supports multimodal input, you can send media in `pgpt.messages[].content[]` (the same request shape used by both thread interactions and one-shot chat).
You can mix multiple content blocks in one message. Supported block types in the schema:
| Type | Typical use | Required fields | Notes |
| - | - | - | - |
| `text` | Plain text prompt/input | none | Uses `text`; supports optional `citations` metadata. |
| `image` | Image attachment | `data` | `data` can be base64 or URL; optional `mime_type`. |
| `audio` | Audio attachment | `data` | `data` can be base64 or URL; optional `mime_type`. |
| `binary` | Generic binary payload | `data`, `mime_type` | Optional `filename`. |
| `file` | File/document content block | `content` | Optional `content_type`, `doc_metadata`. |
| `tool_use` | Tool call request | `id`, `name`, `input` | Internal/tool orchestration block. |
`start_timestamp`, `stop_timestamp`, and `_meta` are optional on all blocks.
```json theme={null}
[
{ "type": "text", "text": "Summarize this image." },
{ "type": "image", "data": "", "mime_type": "image/png" },
{ "type": "audio", "data": "", "mime_type": "audio/mpeg" },
{ "type": "binary", "data": "", "mime_type": "application/octet-stream", "filename": "blob.bin" },
{
"type": "file",
"content": "",
"content_type": "application/pdf",
"doc_metadata": { "file_name": "contract.pdf", "file_type": "pdf" }
},
{
"type": "source",
"sources": [
{
"type": "context.website",
"url": "https://example.com/report",
"title": "Quarterly Report",
"description": "Public report page"
},
{
"type": "context.chunk",
"id": "chunk_01",
"score": 0.92,
"text": "Support backlog dropped 8% week-over-week",
"document": {
"object": "artifact",
"artifact": "artifact_123",
"doc_metadata": { "file_name": "support.csv", "file_type": "csv" }
}
}
]
},
{ "type": "tool_use", "id": "toolu_123", "name": "semantic_search", "input": { "query": "billing issues" } },
{
"type": "tool_result",
"tool_use_id": "toolu_123",
"content": [{ "type": "text", "text": "Found 5 matching passages." }],
"is_error": false
},
{ "type": "thinking", "thinking": "I should compare the latest week to the previous one." },
{
"type": "tldr",
"content": [
{ "type": "text", "text": "User: Analyze support trend" },
{ "type": "text", "text": "Assistant: Backlog decreased 8%" }
]
}
]
```
Example interaction request with image + text and runtime flags:
| Type | Name | Required | Notes |
| - | - | - | - |
| Path | `threadID` | Yes | Thread identifier. |
| Body | `thread_id` | Yes | Thread identifier. |
| Body | `pgpt` | Yes | Chat request body. |
| Body | `artifact_ids` | No | Artifact IDs to use as context. |
| Body | `all_artifacts` | No | Include all available artifacts when `true`. |
| Body | `agent` | No | Agent preset to use. |
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/thread/{threadID}/interaction" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"thread_id": "{threadID}",
"all_artifacts": true,
"artifact_ids": [],
"agent": "Default",
"pgpt": {
"messages": [
{
"role": "user",
"content": [
{
"type": "image",
"data": "",
"mime_type": "image/png"
},
{
"type": "text",
"text": "What do you see here?"
}
]
}
],
"system": {
"use_default_prompt": true,
"citations": {
"enabled": true
}
},
"thinking": {
"enabled": true
}
}
}'
```
* `system.citations.enabled`: asks the model to include citation references when available.
* `thinking.enabled`: enables deep thinking mode; responses can take longer but are typically better reasoned.
## Create or list threads
Create a new thread in a project:
| Type | Name | Required | Notes |
| - | - | - | - |
| Path | `projectID` | Yes | Project identifier. |
| Body | `name` | Yes | Thread name. |
| Body | `visibility` | Yes | `Public` or `Private`. |
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/thread" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"name": "Weekly Support Brief",
"visibility": "Private"
}'
```
List threads in a project:
| Type | Name | Required | Notes |
| - | - | - | - |
| Path | `projectID` | Yes | Project identifier. |
| Query | `page` | No | Absolute page number to fetch, 1-based. |
| Query | `page_size` | No | Number of items per page. |
| Query | `page_order` | No | `ASC` or `DESC`. |
| Query | `after` | No | Cursor or value to paginate after. |
| Query | `before` | No | Cursor or value to paginate before. |
| Query | `first` | No | Limit to the first N items after a cursor. |
| Query | `last` | No | Limit to the last N items before a cursor. |
| Query | `total_count` | No | Include total count in the response. |
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/project/{projectID}/thread?page=1&page_size=20" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
{
"data": [
{
"id": "thread_3f2a1c4d5b6e7f8a",
"name": "Weekly Support Brief",
"visibility": "Private",
"created_at": "2026-02-08T14:40:00Z"
}
],
"has_next_page": false,
"has_previous_page": false,
"total_count": 1
}
```
Create a thread and first interaction in one request:
| Type | Name | Required | Notes |
| - | - | - | - |
| Path | `projectID` | Yes | Project identifier. |
| Body | `name` | Yes | New thread name. |
| Body | `visibility` | Yes | `Public` or `Private`. |
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/thread/interaction" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"name": "Weekly Support Brief",
"visibility": "Private"
}'
```
## Update or delete a thread
```bash theme={null}
curl -X PUT "https://{BASE_URL}/api/v1/app/thread/{threadID}" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"name": "Weekly Support Brief",
"visibility": "Private"
}'
```
Delete a thread:
```bash theme={null}
curl -X DELETE "https://{BASE_URL}/api/v1/app/thread/{threadID}" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
## List or fetch interactions
List interactions for a thread:
| Type | Name | Required | Notes |
| - | - | - | - |
| Path | `threadID` | Yes | Thread identifier. |
| Query | `page` | No | Absolute page number to fetch, 1-based. |
| Query | `page_size` | No | Number of items per page. |
| Query | `page_order` | No | `ASC` or `DESC`. |
| Query | `after` | No | Cursor or value to paginate after. |
| Query | `before` | No | Cursor or value to paginate before. |
| Query | `first` | No | Limit to the first N items after a cursor. |
| Query | `last` | No | Limit to the last N items before a cursor. |
| Query | `total_count` | No | Include total count in the response. |
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/thread/{threadID}/interaction?page=1&page_size=20" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
Fetch a specific interaction:
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/interaction/{interactionID}" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
## Delete or stream an interaction
Cancel a running interaction:
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/interaction/{interactionID}/cancel" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
Delete an interaction:
```bash theme={null}
curl -X DELETE "https://{BASE_URL}/api/v1/app/interaction/{interactionID}" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
Stream interaction output:
```bash theme={null}
curl -N "https://{BASE_URL}/api/v1/app/interaction/{interactionID}/stream" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Accept: text/event-stream"
```
```text theme={null}
event: message_start
data: {"type":"message_start","message":{"id":"msg_3d2c1b4a5f6e7d8c","role":"assistant","content":[]}}
event: content_block_delta
data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"• Ticket volume rose 12%"}}
event: message_stop
data: {"type":"message_stop"}
```
## One‑shot chat
If you don’t need a thread, call the chat endpoint directly:
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/chat" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{
"role": "user",
"content": [
{ "type": "text", "text": "Draft a 2-sentence update on this week’s support backlog." }
]
}
],
"max_tokens": 64,
"temperature": 0.3
}'
```
```json theme={null}
{
"id": "msg_5f2e1d3c4b6a7c8d",
"role": "assistant",
"content": [
{ "type": "text", "text": "Backlog volume dipped 8% this week after closing high-priority billing cases. We’ll focus next on resolving long-tail authentication issues." }
]
}
```
## Validate a chat request
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/chat/validate" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{
"role": "user",
"content": [
{ "type": "text", "text": "Give me a three-bullet summary of the Q1 support plan." }
]
}
],
"max_tokens": 64,
"temperature": 0.3
}'
```
## Available tools
Pass tools in `pgpt.tools` as `{ "name": "...", "type": "..." }`.
| Name | Type | What it does |
| - | - | - |
| `semantic_search` | `semantic_search_v1` | Searches indexed project/workspace knowledge by semantic similarity. |
| `file_sematic_search` | `file_semantic_search_v1` | Searches file-based content and attachments semantically. |
| `tabular_analysis` | `tabular_analysis_v1` | Analyzes tabular datasets and returns computed insights. |
| `database_query` | `database_query_v1` | Runs database lookups/queries through configured data sources. |
| `web_search` | `web_search_v1` | Performs web search for external/public information. |
| `web_extract` | `web_extract_v1` | Extracts structured text/content from URLs. |
| `list_project_files` | `list_project_files_v1` | Lists files in the current project for downstream tool usage. |
## Errors and edge cases
* **400**: invalid message schema (use `/chat/validate`).
* **404**: thread or interaction not found.
* **409**: interaction already completed when canceling.
# Artifacts
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/workspace-api/content/artifacts
Workspace artifacts for documents, AI Documents, and connectors.
An artifact is a piece of information **or tool** you provide to Zylon so it can be used as context for queries and operations. The Workspace API groups artifacts into **document artifacts**, **AI Documents**, and **other artifacts**.
## Prerequisites
* An API token. See [Workspace Token Management](/en/v1.57/developer-manual/get-started/token-management).
* Your Zylon hostname (replace `{BASE_URL}` in the examples).
## Artifacts
| Category | Includes | When to use |
| - | - | - |
| **Document artifacts** | Documents, folders, links | Store or organize content inside a project. |
| **AI Documents** | Summary, composition, extraction flows | Run workflows across artifacts to produce outputs. |
| **Other artifacts** | MCP servers, SQL databases | Provide external tools or data sources. |
### Artifact request fields
Use `POST /api/v1/app/project/{projectID}/artifact` to create any artifact type. The path provides the project; the body provides shared artifact metadata plus a type-specific `props` object.
| Field | Type | Required | Description |
| - | - | - | - |
| `projectID` | path | Yes | Project identifier. |
| `type` | string | Yes | Artifact type. Client-facing create types include `Document`, `Folder`, `Link`, `Summary`, `Composition`, `BulkQA`, `ReadAndExtract`, `Analysis`, `SmartDoc`, `SqlDatabase`, and `McpServer`. |
| `name` | string | Yes | Artifact display name. |
| `props` | object | Yes | Type-specific configuration. The legacy alias `config` is also accepted. |
| `source` | string | No | Artifact source. Defaults to `User`. |
| `description` | string | No | Human-readable description. |
| `parent_id` | string | No | Parent artifact ID for tree artifacts such as documents, folders, and links. Do not use it for MCP or database artifacts. |
| `integration_id` | string | No | Integration ID for integration-backed artifacts. |
| `external_url` | string | No | External URL for link-like or connector-backed artifacts. |
| `raw_content` | string | No | Inline raw content for artifact types that accept text content. |
| `keep_file_after_ingestion` | boolean | No | Whether uploaded file data should be retained after ingestion. Defaults to `true`. |
| `interaction_id` | string | No | Interaction that produced this artifact, when applicable. |
| `private_props` | object | No | Private connector configuration for MCP and SQL database artifacts. The legacy alias `private_config` is also accepted. |
| `ws_auto_select` | boolean | No | Whether Workspace should auto-select an MCP or SQL database artifact as chat context. Defaults to `false`. |
| `fileData` | file | No | Multipart-only file binary for upload-backed artifacts such as `Document` and `Skill`. |
### Document artifacts
Document artifacts hold content, links reference existing artifacts, and folders organize artifacts inside a project.
| Field | Type | Required | Description |
| - | - | - | - |
| `file_name` | string | Yes | Original file name. |
| `content_type` | string | Yes | MIME type of `fileData`. |
| `content_length` | integer | Yes | File size in bytes. Must match the uploaded file bytes. |
| `metadata` | object | No | Provider-specific metadata for integration-backed documents. |
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-F 'type=Document' \
-F 'name=Q1 Support Summary' \
-F 'props={
"content_type":"text/plain",
"file_name":"q1-support-summary.txt",
"content_length":79
};type=application/json' \
-F 'fileData=@./q1-support-summary.txt;type=text/plain'
```
```json theme={null}
{
"id": "artifact_doc_q1",
"project_id": "proj_7a5c3e1b9d2f4a6c",
"name": "Q1 Support Summary",
"type": "Document",
"source": "User",
"state": "Published",
"ingest_status": "Done",
"has_content": true,
"props": {
"file_name": "q1-support-summary.txt",
"content_type": "text/plain",
"content_length": 79
},
"created_at": "2026-02-08T14:30:12Z",
"updated_at": "2026-02-08T14:31:02Z"
}
```
| Field | Type | Required | Description |
| - | - | - | - |
| `metadata` | object | No | Provider-specific metadata for integration-backed folders. Use `{}` for user-created folders without metadata. |
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"type": "Folder",
"source": "User",
"name": "Q1 Support",
"description": "Artifacts for Q1 support work.",
"parent_id": null,
"props": {}
}'
```
```json theme={null}
{
"id": "artifact_folder_q1",
"project_id": "proj_7a5c3e1b9d2f4a6c",
"name": "Q1 Support",
"parent_id": null,
"type": "Folder",
"source": "User",
"state": "Published",
"child_count": 0,
"ingest_status": "NotApplicable",
"props": {},
"created_at": "2026-02-08T14:32:10Z",
"updated_at": "2026-02-08T14:32:10Z"
}
```
| Field | Type | Required | Description |
| - | - | - | - |
| `original_artifact_id` | string | Yes | Artifact to link into this project or folder. |
| `source_artifact_id` | string | Response only | Canonical source artifact ID. The server sets this value. |
| `original_artifact_type` | string | Response only | Type of the original artifact. The server sets this value. |
| `original_project_id` | string \| null | Response only | Project that owns the original artifact, when available. |
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"type": "Link",
"source": "User",
"name": "Q1 Support Summary (link)",
"description": "Reference to the canonical document.",
"parent_id": "artifact_folder_q1",
"props": {
"original_artifact_id": "{artifactID}"
}
}'
```
```json theme={null}
{
"id": "artifact_link_q1",
"project_id": "proj_7a5c3e1b9d2f4a6c",
"name": "Q1 Support Summary (link)",
"parent_id": "artifact_folder_q1",
"type": "Link",
"source": "User",
"state": "Published",
"ingest_status": "NotApplicable",
"props": {
"source_artifact_id": "artifact_doc_q1",
"original_artifact_id": "artifact_doc_q1",
"original_artifact_type": "Document",
"original_project_id": "proj_7a5c3e1b9d2f4a6c"
},
"created_at": "2026-02-08T14:33:22Z",
"updated_at": "2026-02-08T14:33:22Z"
}
```
### AI Documents
AI Documents run a Zylon workflow across one or more artifacts to produce a structured output.
| Field | Type | Required | Description |
| - | - | - | - |
| `artifact_ids` | string\[] | Yes | Input artifacts to summarize. |
| `style` | string | Yes | `Expert`, `Neutral`, or `Simple`. Deprecated values may still decode but should not be used. |
| `detail` | string | Yes | `KeyPoints`, `ShortPieces`, or `LongPieces`. Deprecated values may still decode but should not be used. |
| `instructions` | string\[] \| null | No | Extra instructions for the summary generation. |
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"type": "Summary",
"source": "User",
"name": "Q1 Support Summary (auto)",
"props": {
"artifact_ids": ["{artifactID}"],
"style": "Neutral",
"detail": "KeyPoints",
"instructions": ["Focus on billing and onboarding trends."]
}
}'
```
```json theme={null}
{
"id": "artifact_summary_q1",
"project_id": "proj_7a5c3e1b9d2f4a6c",
"type": "Summary",
"state": "Processing",
"ingest_status": "Processing",
"props": {
"artifact_ids": ["artifact_doc_q1"],
"style": "Neutral",
"detail": "KeyPoints",
"instructions": ["Focus on billing and onboarding trends."]
},
"created_at": "2026-02-08T15:10:00Z"
}
```
| Field | Type | Required | Description |
| - | - | - | - |
| `artifact_ids` | string\[] | Yes | Input artifacts to use for the draft. |
| `instructions` | string | Yes | Composition prompt or drafting instructions. |
| `style` | string | Yes | `Expert`, `Neutral`, or `Simple`. |
| `detail` | string | Yes | `KeyPoints`, `ShortPieces`, or `LongPieces`. |
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"type": "Composition",
"source": "User",
"name": "Q1 Support Brief",
"props": {
"artifact_ids": ["{artifactID}"],
"style": "Expert",
"detail": "LongPieces",
"instructions": "Draft a one-page summary for leadership."
}
}'
```
```json theme={null}
{
"id": "artifact_comp_q1",
"project_id": "proj_7a5c3e1b9d2f4a6c",
"type": "Composition",
"state": "Processing",
"ingest_status": "Processing",
"props": {
"artifact_ids": ["artifact_doc_q1"],
"style": "Expert",
"detail": "LongPieces",
"instructions": "Draft a one-page summary for leadership."
},
"created_at": "2026-02-08T15:12:40Z"
}
```
| Field | Type | Required | Description |
| - | - | - | - |
| `questions` | string\[] | Yes | Questions to answer. |
| `artifact_ids` | string\[] | Yes | Input artifacts to answer from. |
| `instructions` | string\[] | Yes | Constraints or guidance for the answers. |
| `detail` | string | Yes | `Concise`, `Moderate`, or `Comprehensive`. |
| `style` | string | Yes | `Expert`, `Neutral`, or `Simple`. |
| `results` | object\[] | No | Server-populated answer results. Defaults to `[]`. |
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"type": "BulkQA",
"source": "User",
"name": "Billing FAQ",
"props": {
"artifact_ids": ["{artifactID}"],
"style": "Simple",
"detail": "Concise",
"instructions": ["Answer using only the artifacts."],
"questions": [
"What are the top billing issues?",
"How quickly were priority bugs resolved?"
]
}
}'
```
```json theme={null}
{
"id": "artifact_bulkqa_q1",
"project_id": "proj_7a5c3e1b9d2f4a6c",
"type": "BulkQA",
"state": "Processing",
"ingest_status": "Processing",
"props": {
"artifact_ids": ["artifact_doc_q1"],
"style": "Simple",
"detail": "Concise",
"instructions": ["Answer using only the artifacts."],
"questions": [
"What are the top billing issues?",
"How quickly were priority bugs resolved?"
]
},
"created_at": "2026-02-08T15:14:10Z"
}
```
| Field | Type | Required | Description |
| - | - | - | - |
| `artifact_ids` | string\[] | Yes | Input artifacts to read. |
| `sections` | object\[] | Yes | Extraction targets. |
| `sections[].id` | string | Yes | Stable section ID. |
| `sections[].title` | string | Yes | Section title. |
| `sections[].description` | string | Yes | What to extract for that section. |
| `results` | object\[] | Response only | Extracted section results. |
| `organization_context` | string \| null | Response only | Organization context used by the server. |
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"type": "ReadAndExtract",
"source": "User",
"name": "Contract extraction",
"props": {
"artifact_ids": ["{artifactID}"],
"sections": [
{ "title": "Term", "description": "Contract term in months", "id": "term" },
{ "title": "SLA", "description": "Support response time", "id": "sla" }
]
}
}'
```
```json theme={null}
{
"id": "artifact_readextract_v3",
"project_id": "proj_7a5c3e1b9d2f4a6c",
"type": "ReadAndExtract",
"state": "Processing",
"ingest_status": "Processing",
"props": {
"artifact_ids": ["artifact_doc_q1"],
"sections": [
{ "title": "Term", "description": "Contract term in months", "id": "term" },
{ "title": "SLA", "description": "Support response time", "id": "sla" }
]
},
"created_at": "2026-02-08T15:15:55Z"
}
```
| Field | Type | Required | Description |
| - | - | - | - |
| `artifact_ids` | string\[] | Yes | Input artifacts to analyze. |
| `instruction` | object \| null | No | Custom analysis instruction. If omitted, the server uses its default analysis prompt. |
| `instruction.id` | string | Yes when `instruction` is set | Stable instruction ID. |
| `instruction.prompt` | string | Yes when `instruction` is set | Prompt used for analysis. |
| `instruction.metadata` | object | No | Extra instruction metadata. Defaults to `{}`. |
| `result` | object \| null | Response only | Combined analysis output. |
| `organization_context` | string \| null | Response only | Organization context used by the server. |
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"type": "Analysis",
"source": "User",
"name": "Support trend analysis",
"props": {
"artifact_ids": ["{artifactID}"],
"instruction": {
"id": "support_trends",
"prompt": "Find the top support trends and risks.",
"metadata": { "audience": "leadership" }
}
}
}'
```
```json theme={null}
{
"id": "artifact_analysis_q1",
"project_id": "proj_7a5c3e1b9d2f4a6c",
"type": "Analysis",
"state": "Processing",
"ingest_status": "NotApplicable",
"props": {
"artifact_ids": ["artifact_doc_q1"],
"instruction": {
"id": "support_trends",
"prompt": "Find the top support trends and risks.",
"metadata": { "audience": "leadership" }
},
"result": null
},
"created_at": "2026-02-08T15:16:30Z"
}
```
SmartDoc creation accepts `props`, but the server initializes SmartDoc artifacts with an empty object. Send `{}`.
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"type": "SmartDoc",
"source": "User",
"name": "Onboarding SmartDoc",
"props": {}
}'
```
```json theme={null}
{
"id": "artifact_smartdoc_q1",
"project_id": "proj_7a5c3e1b9d2f4a6c",
"type": "SmartDoc",
"state": "Draft",
"ingest_status": "NotApplicable",
"props": {},
"created_at": "2026-02-08T15:17:20Z"
}
```
### Other artifacts
Connector artifacts store tool integrations. `private_props` is only used for **MCP** and **SQL database** artifacts.
| Field | Type | Required | Description |
| - | - | - | - |
| `schemas` | string\[] \| null | No | Database schemas to expose. |
| `tables` | string\[] \| null | No | Database tables to expose. |
| `ssl` | boolean \| null | No | Whether the database connection uses SSL. |
| `enable_tables` | boolean \| null | No | Enable table discovery/use. |
| `enable_views` | boolean \| null | No | Enable view discovery/use. |
| `enable_procedures` | boolean \| null | No | Enable stored procedure discovery/use. |
| `enable_functions` | boolean \| null | No | Enable function discovery/use. |
| `private_props.connection_string` | string | Yes | Database connection string. Mask secrets in examples and logs. |
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"type": "SqlDatabase",
"source": "User",
"name": "Sales database",
"description": "Read-only reporting database.",
"props": {
"schemas": ["public", "analytics"],
"tables": ["orders", "customers"],
"ssl": true,
"enable_tables": true,
"enable_views": true,
"enable_procedures": false,
"enable_functions": false
},
"private_props": {
"connection_string": "postgresql://readonly:***@db.example.com:5432/sales"
}
}'
```
```json theme={null}
{
"id": "artifact_db_sales",
"project_id": "proj_7a5c3e1b9d2f4a6c",
"type": "SqlDatabase",
"state": "Published",
"ingest_status": "NotApplicable",
"props": {
"schemas": ["public", "analytics"],
"tables": ["orders", "customers"],
"ssl": true,
"enable_tables": true,
"enable_views": true,
"enable_procedures": false,
"enable_functions": false
},
"created_at": "2026-02-08T15:20:05Z"
}
```
| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | MCP server name visible to tools. |
| `tool_configuration` | object \| null | No | Tool allowlist configuration. |
| `tool_configuration.enabled` | boolean | No | Whether tools are enabled. Defaults to `true`. |
| `tool_configuration.allowed_tools` | string\[] \| null | No | Tool names clients may call through this MCP server. |
| `private_props.url` | string | Yes | MCP server URL. |
| `private_props.use_bearer_auth` | boolean | No | Whether to authenticate with bearer auth. Defaults to `false`. |
| `private_props.authorization_token` | string \| null | No | Authorization token when the server expects a custom authorization token. Mask the value. |
| `private_props.bearer_token` | string \| null | No | Bearer token when bearer auth is enabled. Mask the value. |
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"type": "McpServer",
"source": "User",
"name": "Internal tools",
"props": {
"name": "internal_mcp",
"tool_configuration": {
"enabled": true,
"allowed_tools": ["crm_lookup", "ticket_search"]
}
},
"private_props": {
"url": "https://mcp.internal.zylon",
"authorization_token": "***"
}
}'
```
```json theme={null}
{
"id": "artifact_mcp_internal",
"project_id": "proj_7a5c3e1b9d2f4a6c",
"type": "McpServer",
"state": "Published",
"ingest_status": "NotApplicable",
"props": {
"name": "internal_mcp",
"tool_configuration": {
"enabled": true,
"allowed_tools": ["crm_lookup", "ticket_search"]
}
},
"created_at": "2026-02-08T15:22:30Z"
}
```
To retrieve private details for these artifacts, call:
`GET /api/v1/app/project/{projectId}/artifact/{artifactId}/private`
Only the creator of the artifact can access the private details.
## Working with artifacts
### List artifacts
| Query parameter | Type | Required | Description |
| - | - | - | - |
| `state` | string | No | Comma-separated artifact states. Defaults to `Published,Processing`. |
| `source` | string | No | Comma-separated sources such as `User`, `SharePoint`, `Confluence`, `Claromentis`, or `FileSystem`. |
| `ingest_status` | string | No | Comma-separated ingest statuses. Defaults to all statuses. |
| `type` | string | No | Comma-separated artifact types. |
| `parent_id` | string | No | Scope results to direct children of a parent artifact. |
| `include_descendants` | boolean | No | Include the full subtree under `parent_id`; if no parent is set, include all descendants in the project. |
| `filter_by_text` | string | No | Text search over artifact names and content metadata. |
| `keep_ancestors` | boolean | No | Include ancestor artifacts for text matches. |
| `resolve_links` | boolean | No | Include descendants of link artifacts. |
| `sub_type` | string | No | Comma-separated subtype filter. |
| `include` | string | No | Use `User` to include creator details. |
| `page`, `page_size`, `after`, `before` | mixed | No | Pagination controls. |
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact?page=1&page_size=20&parent_id={artifactID}&include_descendants=false" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
{
"data": [
{
"id": "artifact_doc_q1",
"project_id": "proj_7a5c3e1b9d2f4a6c",
"name": "Q1 Support Summary",
"type": "Document",
"source": "User",
"state": "Published",
"ingest_status": "Done",
"has_content": true,
"parent_id": "artifact_folder_q1",
"child_count": 0,
"keep_file_after_ingestion": true,
"ws_auto_select": false,
"created_at": "2026-02-08T14:30:12Z",
"updated_at": "2026-02-08T14:31:02Z"
}
],
"has_next_page": false,
"has_previous_page": false,
"total_count": 1
}
```
### Get an artifact
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/{artifactID}" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
{
"id": "artifact_doc_q1",
"project_id": "proj_7a5c3e1b9d2f4a6c",
"name": "Q1 Support Summary",
"type": "Document",
"source": "User",
"state": "Published",
"ingest_status": "Done",
"has_content": true,
"parent_id": "artifact_folder_q1",
"child_count": 0,
"keep_file_after_ingestion": true,
"ws_auto_select": false,
"created_at": "2026-02-08T14:30:12Z",
"updated_at": "2026-02-08T14:31:02Z"
}
```
| Response field | Type | Description |
| - | - | - |
| `id` | string | Artifact ID. |
| `parent_id` | string \| null | Parent artifact ID, when the artifact is nested. |
| `child_count` | integer | Number of direct children. |
| `project_id` | string | Project ID. |
| `name` | string | Artifact name. |
| `description` | string \| null | Artifact description. |
| `type` | string | Artifact type. |
| `source` | string | Artifact source. |
| `state` | string | Current artifact state. |
| `error` | string \| null | Ingest or processing error code. |
| `ingest_status` | string | Ingest lifecycle status. |
| `ingest_warnings` | string\[] \| null | Non-fatal ingest warnings. |
| `ingest_progress` | number \| null | Ingest progress when available. |
| `has_content` | boolean | Whether content is stored for the artifact. |
| `raw_content` | string \| null | Raw content when explicitly included. |
| `integration_id` | string \| null | Integration ID for integration-backed artifacts. |
| `external_url` | string \| null | External URL when present. |
| `props` | object | Type-specific public configuration. |
| `file_uri` | string \| null | Temporary public file URL when available. |
| `artifact_references` | object\[] \| null | References when `include_references=true`. |
| `artifact_relationships` | object\[] \| null | Relationships when `include_relationships=true`. |
| `keep_file_after_ingestion` | boolean | Whether uploaded file data is retained. |
| `created_by` | object \| null | Creator details when `include=User`. |
| `created_at` | timestamp | Creation timestamp. |
| `updated_at` | timestamp | Last update timestamp. |
| `ws_auto_select` | boolean | Whether Workspace auto-selects the artifact as context. Only meaningful for MCP and SQL database artifacts. |
### Update an artifact
| Field | Type | Required | Description |
| - | - | - | - |
| `projectID` | path | Yes | Project identifier. |
| `artifactID` | path | Yes | Artifact identifier. |
| `name` | string | No | New artifact name. |
| `parent_id` | string | No | Move a content/tree artifact under this parent artifact. Do not use it for MCP or database artifacts. |
| `reset_parent_id` | boolean | No | Set to `true` to move a content/tree artifact back to the project root. Defaults to `false`. |
| `external_url` | string | No | Replace the external URL. |
| `props` | object | No | Replace or update type-specific public configuration. The legacy alias `config` is also accepted. |
| `description` | string | No | Replace the description. |
| `content` | string | No | Base64-encoded binary content. |
| `plain_text_content` | string | No | Plain text content to store for the artifact. |
| `private_props` | object | No | Private connector configuration for MCP and SQL database artifacts. The legacy alias `private_config` is also accepted. |
| `ws_auto_select` | boolean | No | Whether Workspace should auto-select an MCP or SQL database artifact as chat context. Do not use it for document or agent-flow artifacts. |
```bash theme={null}
curl -X PUT "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/{artifactID}" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"name": "Q1 Support Summary (final)",
"description": "Finalized weekly summary notes.",
"parent_id": "artifact_folder_q1",
"reset_parent_id": false,
"plain_text_content": "Ticket volume rose 12% week-over-week..."
}'
```
```json theme={null}
{
"id": "artifact_doc_q1",
"name": "Q1 Support Summary (final)",
"description": "Finalized weekly summary notes.",
"parent_id": "artifact_folder_q1",
"type": "Document",
"source": "User",
"ingest_status": "Done",
"updated_at": "2026-02-08T14:45:21Z"
}
```
Use `parent_id` to move an artifact into a folder. Use `reset_parent_id: true` to remove the current parent and move it back to the project root.
### Delete an artifact
```bash theme={null}
curl -X DELETE "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/{artifactID}" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
{
"id": "artifact_doc_q1",
"state": "Deleted"
}
```
### Private artifact metadata
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/{artifactID}/private" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
{
"connection_string": "postgresql://readonly:***@db.example.com:5432/sales"
}
```
### Download raw artifact content
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/{artifactID}/download" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```text theme={null}
Ticket volume rose 12% week-over-week. Billing issues drove 38% of cases.
```
### Get parsed content
This endpoint is only available when the artifact has an initialized vector index.
In practice, this usually means connector-backed documents or artifacts that have completed indexing.
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/{artifactID}/parsed-content" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}"
```
```text theme={null}
# Q1 Support Summary
Billing issues drove 38% of support cases.
```
### Sync an artifact
This endpoint is primarily used for integration artifacts (SharePoint, Confluence, Claromentis, or FileSystem).
```bash theme={null}
curl -N -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/{artifactID}/sync" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Accept: text/event-stream"
```
The request body is empty. The response is an SSE stream emitted by the integration sync process.
```text theme={null}
event: sync_started
data: {"current_artifact_count":12,"integration_item_count":40}
event: sync_progress
data: {"artifact_id":"artifact_doc_q1","op":"Updated","progress":0.42}
event: sync_completed
data: {}
```
### Bulk update artifacts
Use the bulk update endpoint to apply the same update body shape used by `PUT /artifact/{artifactID}` to multiple artifacts.
| Type | Name | Required | Notes |
| - | - | - | - |
| Path | `projectID` | Yes | Project identifier. |
| Body | `artifacts` | Yes | Array of artifact updates. |
| Body | `artifacts[].artifactId` | Yes | Artifact identifier to update. |
| Body | `artifacts[].update` | Yes | Update body using the same fields as `PUT /artifact/{artifactID}`. |
```bash theme={null}
curl -X PUT "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/bulk" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"artifacts": [
{
"artifactId": "artifact_doc_q1",
"update": {
"parent_id": "artifact_folder_q1",
"reset_parent_id": false,
"description": "Moved into Q1 folder."
}
}
]
}'
```
```json theme={null}
[
{
"id": "artifact_doc_q1",
"parent_id": "artifact_folder_q1",
"description": "Moved into Q1 folder.",
"type": "Document",
"state": "Published",
"ingest_status": "Done",
"updated_at": "2026-02-08T15:20:00Z"
}
]
```
### Bulk delete artifacts
| Type | Name | Required | Notes |
| - | - | - | - |
| Path | `projectID` | Yes | Project identifier. |
| Body | `artifact_ids` | Yes | Artifact identifiers to delete. |
```bash theme={null}
curl -X DELETE "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact/bulk" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"artifact_ids": ["artifact_doc_q1", "artifact_link_q1"]
}'
```
```json theme={null}
[
{
"id": "artifact_doc_q1",
"state": "Deleted"
},
{
"id": "artifact_link_q1",
"state": "Deleted"
}
]
```
## Check linked artifacts before modifying
Use this endpoint before changing an artifact when you need to check whether linked artifacts depend on it.
| Type | Name | Required | Notes |
| - | - | - | - |
| Query | `created_by` | No | User ID that created the artifacts to check. |
| Query | `project_id` | No | Project ID to check for linked artifacts. |
| Query | `artifact_id` | No | Artifact ID to check for linked artifacts. |
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/resource/is-safe-to-modify?project_id={projectID}&artifact_id={artifactID}" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}"
```
```json theme={null}
{
"has_linked_artifacts": false
}
```
## Errors and edge cases
* **Artifact error codes**: the `error` field maps to ingest failures:
| `error` value | Meaning |
| - | - |
| `InvalidExtension` | File extension is not supported. |
| `MismatchedType` | File type does not match the declared artifact type. |
| `Malformed` | File is corrupt or unreadable. |
| `Encrypted` | File is password‑protected. |
| `ParsingFailure` | Extractor failed to parse the file. |
| `MaxNodes` | Document is too large/complex for parsing. |
| `NoValidFile` | No valid file was found in the upload. |
| `NoValidNodes` | No parseable content was extracted. |
| `InternalError` | Ingest pipeline failed unexpectedly. |
| `Unknown` | Unclassified ingest failure. |
If `ingest_status` is `Error`, fix the source file (or convert it) and re‑sync.
* **Warnings**: `ingest_warnings` can include values like `BigSize`, `UnprocessableContent`, or `NoContent` to indicate non‑fatal issues.
* **401/403**: token missing or insufficient permissions.
* **404**: artifact or project not found.
* **409**: artifact already processing.
* **413**: content exceeds the recommended upload size (250 MB).
# Analytics
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/workspace-api/general/analytics
Track usage totals, rankings, and time series metrics.
Analytics endpoints summarize how your workspace is being used across projects and users.
## Basic request and response
Start with totals to get a usage snapshot from `GET /api/v1/app/organization/analytics/totals`.
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/organization/analytics/totals" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
{
"projects_total": 12,
"threads_total": 184,
"interactions_total": 1420,
"agent_flows_total": 36,
"uploaded_artifacts_total": 87
}
```
## Active users ranking
| Type | Name | Required | Notes |
| - | - | - | - |
| Query | `start_date` | No | Start of the reporting window as a Unix timestamp. |
| Query | `end_date` | No | End of the reporting window as a Unix timestamp. |
| Query | `limit` | No | Maximum number of ranked users to return. |
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/organization/analytics/ranking/active-users?start_date=1738291200&end_date=1738972800&limit=5" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
[
{
"user": {
"id": "user_4b7c2a1d9e5f3c8b",
"org_id": "org_2f3a9d1c7b5e4a8f",
"account_id": "acct_6c8a1f3b2d4e5f7a",
"name": "Sasha Patel",
"email": "sasha@auroralabs.com",
"state": "Active",
"roles": ["AppAdmin"],
"created_at": "2026-02-08T14:12:45Z"
},
"interactions_created": 46,
"agent_flows_created": 4
}
]
```
## Active projects ranking
| Type | Name | Required | Notes |
| - | - | - | - |
| Query | `start_date` | No | Start of the reporting window as a Unix timestamp. |
| Query | `end_date` | No | End of the reporting window as a Unix timestamp. |
| Query | `limit` | No | Maximum number of ranked projects to return. |
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/organization/analytics/ranking/active-projects?start_date=1738291200&end_date=1738972800&limit=5" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
[
{
"project": {
"id": "proj_7a5c3e1b9d2f4a6c",
"name": "Customer Insights",
"goal": "Summarize weekly support trends.",
"deadline": "2026-03-01T00:00:00Z",
"visibility": "Private",
"member_count": 4,
"default_member_role": "Editor",
"default_role_enabled": true,
"project_context": "Support analytics for Q1.",
"answer_context": "Use approved templates.",
"is_pinned": true
},
"interactions_created": 112,
"agent_flows_created": 12
}
]
```
## Time series
| Type | Name | Required | Notes |
| - | - | - | - |
| Query | `start_date` | No | Start of the reporting window as a Unix timestamp. |
| Query | `end_date` | No | End of the reporting window as a Unix timestamp. |
| Query | `type` | Yes | Metric type to return, such as `interactions`. |
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/organization/analytics/timeseries?start_date=1738291200&end_date=1738972800&type=interactions" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
[
{ "date": "2026-02-02", "value": 18 },
{ "date": "2026-02-03", "value": 25 },
{ "date": "2026-02-04", "value": 21 }
]
```
## Errors and edge cases
* **400**: invalid date range or type.
* **403**: insufficient permissions.
# Issues
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/workspace-api/general/issues
Create and manage user-reported issues.
Issues let users report problems with responses or content. Use these endpoints to list, create, update, and close issues.
## List issues
List issues with `GET /api/v1/app/issue` before creating or updating.
| Query parameter | Type | Required | Description |
| - | - | - | - |
| `include` | string | No | Comma-separated list of `User` and `Project` to include related objects. |
| `type` | string | No | Comma-separated issue types: `NoAnswer`, `Inaccurate`, `NoContextUsed`, `Format`, `Other`. |
| `states` | string | No | Comma-separated states: `NotReviewed`, `InReview`, `Closed`, `Deleted`. |
| `start_date` / `end_date` | integer | No | Created-at filter as epoch milliseconds. |
| `filter_by_text` | string | No | Text filter over issue content. |
| `created_by` | string | No | Comma-separated user IDs. |
| `projects` | string | No | Comma-separated project IDs. |
| `page`, `page_size`, `after`, `before` | mixed | No | Pagination controls. |
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/issue?page=1&page_size=20&include=User,Project&states=NotReviewed,InReview" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}"
```
```json theme={null}
{
"data": [
{
"id": "issue_5c4b3a2d1e0f9a8b",
"issue_number": 1842,
"description": "Response missed the attached policy details.",
"resource_type": "Thread",
"type": "NoContextUsed",
"state": "NotReviewed",
"is_read": false,
"data": {
"thread_id": "thread_3f2a1c4d5b6e7f8a",
"reported_interaction_id": "interaction_9b8a7c6d5e4f"
},
"created_at": "2026-02-08T14:55:10Z",
"updated_at": "2026-02-08T14:55:10Z",
"created_by": {
"id": "user_4b7c2a1d9e5f3c8b",
"org_id": "org_2f3a9d1c7b5e4a8f",
"account_id": "acct_6c8a1f3b2d4e5f7a",
"name": "Sasha Patel",
"email": "sasha@example.com",
"state": "Active",
"roles": ["AppAdmin"],
"created_at": "2026-02-08T14:12:45Z"
},
"project": {
"id": "proj_7a5c3e1b9d2f4a6c",
"name": "Customer Insights"
}
}
],
"next_cursor": null,
"previous_cursor": null,
"has_next_page": false,
"has_previous_page": false,
"total_count": 1
}
```
## Create an issue
| Type | Name | Required | Notes |
| - | - | - | - |
| Body | `project_id` | Yes | Project where the reported resource lives. |
| Body | `description` | No | User-provided issue description. |
| Body | `resource_type` | Yes | Currently `Thread`. |
| Body | `type` | Yes | One of `NoAnswer`, `Inaccurate`, `NoContextUsed`, `Format`, `Other`. |
| Body | `config` | Yes | Resource-specific payload. For thread issues, provide `thread_id` and `reported_interaction_id`. |
| Body | `anonymous` | Yes | Whether to hide the reporter from the issue payload. |
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/issue" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"project_id": "proj_7a5c3e1b9d2f4a6c",
"description": "Response missed the attached policy details.",
"resource_type": "Thread",
"type": "NoContextUsed",
"config": {
"thread_id": "thread_3f2a1c4d5b6e7f8a",
"reported_interaction_id": "interaction_9b8a7c6d5e4f"
},
"anonymous": false
}'
```
The create request uses `config`. Responses expose the stored issue payload as `data`.
```json theme={null}
{
"id": "issue_5c4b3a2d1e0f9a8b",
"issue_number": 1842,
"description": "Response missed the attached policy details.",
"resource_type": "Thread",
"type": "NoContextUsed",
"state": "NotReviewed",
"is_read": false,
"data": {
"thread_id": "thread_3f2a1c4d5b6e7f8a",
"reported_interaction_id": "interaction_9b8a7c6d5e4f"
},
"created_at": "2026-02-08T14:55:10Z",
"updated_at": "2026-02-08T14:55:10Z"
}
```
## Get or update an issue
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/issue/{issueID}" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}"
```
```json theme={null}
{
"id": "issue_5c4b3a2d1e0f9a8b",
"issue_number": 1842,
"description": "Response missed the attached policy details.",
"resource_type": "Thread",
"type": "NoContextUsed",
"state": "NotReviewed",
"is_read": false,
"data": {
"thread_id": "thread_3f2a1c4d5b6e7f8a",
"reported_interaction_id": "interaction_9b8a7c6d5e4f"
},
"created_at": "2026-02-08T14:55:10Z",
"updated_at": "2026-02-08T14:55:10Z"
}
```
| Type | Name | Required | Notes |
| - | - | - | - |
| Path | `issueID` | Yes | Issue identifier. |
| Body | `description` | No | Updated issue description. |
| Body | `type` | No | Updated issue type. |
| Body | `state` | No | Updated issue state. |
| Body | `is_read` | No | Read flag. Defaults to `false` if omitted, so include the intended value when updating other fields. |
```bash theme={null}
curl -X PUT "https://{BASE_URL}/api/v1/app/issue/{issueID}" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"description": "Reviewed by support.",
"type": "NoContextUsed",
"state": "InReview",
"is_read": true
}'
```
```json theme={null}
{
"id": "issue_5c4b3a2d1e0f9a8b",
"issue_number": 1842,
"description": "Reviewed by support.",
"resource_type": "Thread",
"type": "NoContextUsed",
"state": "InReview",
"is_read": true,
"data": {
"thread_id": "thread_3f2a1c4d5b6e7f8a",
"reported_interaction_id": "interaction_9b8a7c6d5e4f"
},
"created_at": "2026-02-08T14:55:10Z",
"updated_at": "2026-02-08T15:05:10Z"
}
```
## Delete an issue
Delete soft-deletes the issue and returns the updated issue object.
```bash theme={null}
curl -X DELETE "https://{BASE_URL}/api/v1/app/issue/{issueID}" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}"
```
```json theme={null}
{
"id": "issue_5c4b3a2d1e0f9a8b",
"issue_number": 1842,
"resource_type": "Thread",
"type": "NoContextUsed",
"state": "Deleted",
"is_read": true,
"data": {
"thread_id": "thread_3f2a1c4d5b6e7f8a",
"reported_interaction_id": "interaction_9b8a7c6d5e4f"
},
"created_at": "2026-02-08T14:55:10Z",
"updated_at": "2026-02-08T15:10:00Z"
}
```
## Errors and edge cases
* **404**: issue not found.
* **400**: invalid issue state, issue type, or thread issue config.
# Overview
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/workspace-api/general/overview
Monitoring, reporting, and system endpoints for Workspace API.
Use the General section to monitor usage, review issues, search across workspace content, and check system status.
Usage totals, rankings, and time series metrics.
Track user-reported issues and triage feedback.
Query projects, threads, artifacts, and interactions.
Health checks and system status.
# Search
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/workspace-api/general/search
Search across projects, threads, artifacts, artifact content, and interactions.
Use the Search API to query workspace content with a single text query. Limit search scope with the `types` filter.
Search requests require a token with workspace access and a PrivateGPT gateway linked to your organization collection.
## Basic request and response
Search across resources with `GET /api/v1/app/search`.
| Type | Name | Required | Notes |
| - | - | - | - |
| Query | `q` | Yes | Search text. Must be between 3 and 80 characters. |
| Query | `types` | No | Comma-separated list of `Project`, `Artifact`, `ArtifactContent`, `Thread`, and `Interaction`. Defaults to all types. |
| Query | `limit` | No | Maximum results. Defaults to `30` and must be greater than `1`. |
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/search?q=support%20summary&types=Artifact,ArtifactContent&limit=5" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}"
```
```json theme={null}
[
{
"id": "artifact_2b4d6f8a1c3e5a7b",
"type": "Artifact",
"match": "Q1 Support Summary",
"rank": 0.91,
"metadata": {
"name": "Q1 Support Summary",
"type": "Document",
"project_id": "proj_7a5c3e1b9d2f4a6c",
"project_name": "Customer Insights"
}
},
{
"id": "content_8f1a3d5c7b9e",
"type": "ArtifactContent",
"match": "Billing issues drove 38% of support cases.",
"rank": 0.84,
"metadata": {
"name": "Q1 Support Summary",
"type": "Document",
"project_id": "proj_7a5c3e1b9d2f4a6c",
"project_name": "Customer Insights"
}
}
]
```
## Search only threads
| Type | Name | Required | Notes |
| - | - | - | - |
| Query | `q` | Yes | Search text. Must be between 3 and 80 characters. |
| Query | `types` | No | Use `Thread` to limit results to threads. |
| Query | `limit` | No | Maximum results. Defaults to `30` and must be greater than `1`. |
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/search?q=weekly%20brief&types=Thread&limit=5" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}"
```
```json theme={null}
[
{
"id": "thread_3f2a1c4d5b6e7f8a",
"type": "Thread",
"match": "Weekly Support Brief",
"rank": 0.86,
"metadata": {
"name": "Weekly Support Brief",
"project_id": "proj_7a5c3e1b9d2f4a6c",
"project_name": "Customer Insights"
}
}
]
```
## Metadata by result type
| Result type | Metadata shape |
| - | - |
| `Project` | `entity`, containing the project object. |
| `Artifact` | `name`, `type`, `project_id`, `project_name`. |
| `ArtifactContent` | `name`, `type`, `project_id`, `project_name`. |
| `Thread` | `name`, `project_id`, `project_name`. |
| `Interaction` | `content`, `thread_id`, `project_id`, `project_name`, `thread_name`. |
## Errors and edge cases
* **400**: missing `q`, blank query, query outside the 3-80 character range, invalid `types`, or `limit <= 1`.
* **403**: insufficient permissions.
# System
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/workspace-api/general/system
Health checks for workspace availability.
Use these endpoints to verify system status.
## Basic request and response
Use the health check to verify availability with `GET /api/health`.
```bash theme={null}
curl "https://{BASE_URL}/api/health"
```
```json theme={null}
{
"status": "ok",
"uptime": "3d 04:12:33",
"commit": "9f1c2a3"
}
```
## Errors and edge cases
* **503**: health check unavailable.
# Claromentis Integration
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/workspace-api/integrations/claromentis
Sync Claromentis content into your workspace.
Claromentis integrations import knowledge base content. **Enable Claromentis at the instance level first**—see the operator guide: [Claromentis integration setup](/en/v1.57/operator-manual/knowledge-base/claromentis).
## Basic request and response
Create a Claromentis integration with `POST /api/v1/app/integration/claromentis`.
| Type | Name | Required | Notes |
| - | - | - | - |
| Body | `username` | Yes | Claromentis username. |
| Body | `password` | Yes | Claromentis password. |
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/integration/claromentis" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"username": "{username}",
"password": "{password}"
}'
```
```json theme={null}
{
"id": "clar_3c2d1b4a5f6e7d8c",
"user_id": "user_4b7c2a1d9e5f3c8b",
"org_id": "org_2f3a9d1c7b5e4a8f",
"type": "Claromentis",
"created_at": "2026-02-08T14:05:00Z",
"updated_at": "2026-02-08T14:05:00Z"
}
```
## Update integration credentials
| Type | Name | Required | Notes |
| - | - | - | - |
| Path | `integrationID` | Yes | Integration identifier. |
| Body | `username` | Yes | Claromentis username. |
| Body | `password` | Yes | Claromentis password. |
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/integration/claromentis/{integrationID}" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"username": "{username}",
"password": "{password}"
}'
```
```json theme={null}
{
"id": "clar_3c2d1b4a5f6e7d8c",
"user_id": "user_4b7c2a1d9e5f3c8b",
"org_id": "org_2f3a9d1c7b5e4a8f",
"type": "Claromentis",
"created_at": "2026-02-08T14:05:00Z",
"updated_at": "2026-02-08T15:10:00Z"
}
```
## Get integration config
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/integration/claromentis/{integrationID}/config" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
{
"base_url": "https://claromentis.auroralabs.com",
"site": "Knowledge Base"
}
```
## Start an ingest sync
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/integration/claromentis/{integrationID}/ingest" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json"
```
```json theme={null}
{
"type": "sync_started",
"current_artifact_count": 6,
"integration_item_count": 24
}
```
## Errors and edge cases
* **403**: connector not enabled or missing permissions.
* **404**: integration ID not found.
# Confluence Integration
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/workspace-api/integrations/confluence
Read and sync Confluence content into projects.
Confluence integrations pull pages and spaces into your workspace so they can be used as artifacts. **You must enable Confluence at the instance level first**—see the operator guide: [Confluence integration setup](/en/v1.57/operator-manual/knowledge-base/confluence).
If the integration needs OAuth, use the login endpoints in [OpenID & OAuth](/en/v1.57/developer-manual/build-with-zylon/workspace-api/authentication/openid).
## Basic request and response
Fetch integration configuration with `GET /api/v1/app/integration/confluence/{integrationId}/config`.
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/integration/confluence/{integrationID}/config" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
{
"space_key": "SUP",
"base_url": "https://confluence.auroralabs.com"
}
```
## Start an ingest sync
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/integration/confluence/{integrationID}/ingest" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
{
"type": "sync_started",
"current_artifact_count": 42,
"integration_item_count": 120
}
```
## ConfluenceLocal endpoints
Use these endpoints when your deployment uses the `confluencelocal` provider with basic-auth credentials.
### Create a ConfluenceLocal integration
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/integration/confluencelocallegacy" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"username": "{user}",
"password": "{password}"
}'
```
### Update a ConfluenceLocal integration
| Type | Name | Required | Notes |
| - | - | - | - |
| Path | `integrationID` | Yes | Integration identifier. |
| Body | `username` | Yes | ConfluenceLocal username. |
| Body | `password` | Yes | ConfluenceLocal password. |
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/integration/confluencelocallegacy/{integrationID}" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"username": "{user}",
"password": "{password}"
}'
```
### Get ConfluenceLocal config
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/integration/confluencelocallegacy/{integrationID}/config" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
### Start ConfluenceLocal ingest
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/integration/confluencelocallegacy/{integrationID}/ingest" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json"
```
```json theme={null}
{
"id": "int_6d9a2b4c5e7f",
"user_id": "user_4b7c2a1d9e5f3c8b",
"org_id": "org_2f3a9d1c7b5e4a8f",
"type": "ConfluenceLocalLegacy",
"provider_data": {
"username": "confluence_service"
},
"created_at": "2026-03-01T11:00:00Z",
"updated_at": "2026-03-01T11:00:00Z"
}
```
## Common mistakes
* Using the OAuth-style Confluence endpoints with a `confluencelocal` integration ID.
* Forgetting to include JSON body fields (`username`, `password`) for create/update.
* Calling ingest before the integration is configured.
## Errors and edge cases
* **403**: integration not enabled or missing permissions.
* **404**: integration ID not found.
# Filesystem Integration
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/workspace-api/integrations/filesystem
Sync files from a shared filesystem into your workspace.
The filesystem integration connects a shared directory to your workspace. **Enable the filesystem connector first** in the operator guide: [Filesystem integration setup](/en/v1.57/operator-manual/knowledge-base/file-system).
## Basic request and response
Create a filesystem integration with `POST /api/v1/app/integration/filesystem`.
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/integration/filesystem" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"username": "{file_system_username}",
"password": "{file_system_password}"
}'
```
```json theme={null}
{
"id": "fs_9f8e7d6c5b4a3c2d",
"user_id": "user_4b7c2a1d9e5f3c8b",
"org_id": "org_2f3a9d1c7b5e4a8f",
"type": "FileSystem",
"created_at": "2026-02-08T14:10:00Z",
"updated_at": "2026-02-08T14:10:00Z"
}
```
## Update integration credentials
| Type | Name | Required | Notes |
| - | - | - | - |
| Path | `integrationID` | Yes | Integration identifier. |
| Body | `username` | Yes | Filesystem username. |
| Body | `password` | Yes | Filesystem password. |
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/integration/filesystem/{integrationID}" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"username": "{file_system_username}",
"password": "{file_system_password}"
}'
```
```json theme={null}
{
"id": "fs_9f8e7d6c5b4a3c2d",
"user_id": "user_4b7c2a1d9e5f3c8b",
"org_id": "org_2f3a9d1c7b5e4a8f",
"type": "FileSystem",
"created_at": "2026-02-08T14:10:00Z",
"updated_at": "2026-02-08T15:02:00Z"
}
```
## Get integration config
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/integration/filesystem/{integrationID}/config" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
{
"path": "/mnt/shared/support"
}
```
## Validate credentials
| Type | Name | Required | Notes |
| - | - | - | - |
| Query | `username` | Yes | Filesystem username to validate. |
| Query | `password` | Yes | Filesystem password to validate. |
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/integration/filesystem/validate?username={file_system_username}&password={file_system_password}" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
true
```
## List files
| Type | Name | Required | Notes |
| - | - | - | - |
| Query | `integrationId` | Yes | Filesystem integration identifier. |
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/integration/filesystem/files?integrationId={integrationID}" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
[
{
"path": "/mnt/shared/support/weekly-brief.pdf",
"name": "weekly-brief.pdf",
"size": 287104,
"updated_at": "2026-02-07T19:22:10Z"
}
]
```
## Start an ingest sync
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/integration/filesystem/{integrationID}/ingest" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json"
```
```json theme={null}
{
"type": "sync_started",
"current_artifact_count": 12,
"integration_item_count": 48
}
```
## Errors and edge cases
* **403**: connector not enabled or missing permissions.
* **400**: invalid credentials.
* **404**: integration ID not found.
# SharePoint Integration
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/workspace-api/integrations/sharepoint
Sync SharePoint documents into your workspace.
SharePoint integrations ingest libraries and documents into your workspace. **Enable SharePoint at the instance level first**—see the operator guide: [SharePoint integration setup](/en/v1.57/operator-manual/knowledge-base/sharepoint).
If OAuth is required, use the login endpoints in [OpenID & OAuth](/en/v1.57/developer-manual/build-with-zylon/workspace-api/authentication/openid).
## Basic request and response
Fetch integration configuration with `GET /api/v1/app/integration/sharepoint/{integrationId}/config`.
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/integration/sharepoint/{integrationID}/config" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
{
"site_url": "https://auroralabs.sharepoint.com/sites/support",
"library": "Shared Documents"
}
```
## Start an ingest sync
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/integration/sharepoint/{integrationID}/ingest" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json"
```
```json theme={null}
{
"type": "sync_started",
"current_artifact_count": 18,
"integration_item_count": 64
}
```
## Errors and edge cases
* **403**: integration not enabled or missing permissions.
* **404**: integration ID not found.
# Overview
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/workspace-api/overview
API for automating and managing Zylon Workspace.
The Workspace API lets you programmatically manage **everything in Zylon Workspace**—organizations, users, projects, chats, artifacts, integrations, and reporting. Use it to automate admin workflows or integrate Zylon into your internal systems.
## Base URL
All Workspace endpoints live under:
```
https://{BASE_URL}/api/v1
```
## Organization header (`x-org`)
Workspace endpoints under `/api/v1/app/*` require the `x-org` header so Zylon knows which workspace organization to target.
You can set `x-org` to either:
* the organization slug (recommended), for example `default`
* the organization ID (UUID)
Use this in requests:
```bash theme={null}
-H "x-org: {org_slug}"
```
## Core concepts
| Concept | Meaning |
| - | - |
| **Account** | The identity record that authenticates into Zylon. One account can belong to multiple organizations. |
| **User** | The org-specific representation of an account. An account can have **multiple users**, one per organization. |
| **Artifact** | A persisted piece of knowledge that can be retrieved in chats and tools. |
This model supports multi‑org setups where the same person can be a member of multiple workspaces with different roles.
## Pagination
Pagination is a shared model across the Workspace API. List endpoints return a page envelope with cursors:
```json theme={null}
{
"data": [],
"next_cursor": "cursor_next",
"previous_cursor": "cursor_prev",
"has_next_page": false,
"has_previous_page": false,
"total_count": 0
}
```
Use `page`, `page_size`, `after`, `before`, `first`, `last`, and `total_count` when they’re available on the endpoint.
## Workspace API sections
Analytics, issues, search, and system status endpoints.
SSO login flows and workspace login/auth callbacks.
Create, update, and manage user access and org membership.
Provision projects, manage membership, and control visibility.
Create threads, run interactions, and stream responses.
Manage artifacts and integrations like Confluence, SharePoint, Filesystem, and Claromentis.
For manual log retrieval, use [Backoffice API: Logging](/en/v1.57/developer-manual/build-with-zylon/backoffice-api/logging).
## Errors and edge cases
* **401/403**: token missing or insufficient permissions.
* **404**: resource IDs are invalid or deleted.
* **Redirect endpoints**: login/callback routes return `302` responses intended for browsers.
# Projects
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/workspace-api/projects/project
Create projects, update metadata, and run project-scoped chat.
Projects are the workspace unit that holds threads, artifacts, and team context. Use these endpoints to create and configure projects, transfer ownership, and start project-scoped chats.
## Basic request and response
Create a project with `POST /api/v1/app/project`.
| Type | Name | Required | Notes |
| - | - | - | - |
| Body | `name` | Yes | Project name. |
| Body | `goal` | No | Project goal or description. |
| Body | `deadline` | No | Project deadline as a Unix timestamp. |
| Body | `visibility` | No | `Public` or `Private`. |
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"name": "Customer Insights",
"goal": "Summarize weekly support trends.",
"deadline": 1709337600,
"visibility": "Private"
}'
```
```json theme={null}
{
"id": "proj_7a5c3e1b9d2f4a6c",
"name": "Customer Insights",
"goal": "Summarize weekly support trends.",
"deadline": "2026-03-01T00:00:00Z",
"visibility": "Private",
"member_count": 1,
"default_member_role": "Editor",
"default_role_enabled": true,
"project_context": "Support analytics for Q1.",
"answer_context": "Use approved templates.",
"is_pinned": false
}
```
## Get a project
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/project/{projectID}" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
{
"id": "proj_7a5c3e1b9d2f4a6c",
"name": "Customer Insights",
"goal": "Summarize weekly support trends.",
"visibility": "Private"
}
```
## Update a project
| Type | Name | Required | Notes |
| - | - | - | - |
| Path | `projectID` | Yes | Project identifier. |
| Body | `name` | No | Project name. |
| Body | `goal` | No | Project goal or description. |
| Body | `deadline` | No | Project deadline as an ISO timestamp. |
| Body | `visibility` | No | `Public` or `Private`. |
| Body | `project_context` | No | Project-level context. |
| Body | `answer_context` | No | Default answer guidance. |
| Body | `default_member_role` | No | `Viewer`, `Commenter`, `Editor`, `Admin`, or `Owner`. |
| Body | `default_role_enabled` | No | Enables the default member role. |
```bash theme={null}
curl -X PUT "https://{BASE_URL}/api/v1/app/project/{projectID}" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"name": "Customer Insights",
"goal": "Summarize weekly support and churn signals.",
"deadline": "2026-03-15T00:00:00Z",
"visibility": "Private",
"project_context": "Support analytics for Q1.",
"answer_context": "Return answers in a weekly memo format.",
"default_member_role": "Editor",
"default_role_enabled": true
}'
```
```json theme={null}
{
"id": "proj_7a5c3e1b9d2f4a6c",
"name": "Customer Insights",
"goal": "Summarize weekly support and churn signals.",
"deadline": "2026-03-15T00:00:00Z",
"visibility": "Private",
"member_count": 3,
"default_member_role": "Editor",
"default_role_enabled": true,
"project_context": "Support analytics for Q1.",
"answer_context": "Return answers in a weekly memo format.",
"is_pinned": true
}
```
| Type | Name | Required | Notes |
| - | - | - | - |
| Path | `projectID` | Yes | Project identifier. |
| Body | Any `UpdateProjectDTO` field | No | Partial update; send only fields to change. |
```bash theme={null}
curl -X PATCH "https://{BASE_URL}/api/v1/app/project/{projectID}" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"project_context": "Support analytics for Q1 with strict PII handling."
}'
```
```text theme={null}
HTTP/1.1 200 OK
```
## Delete a project
```bash theme={null}
curl -X DELETE "https://{BASE_URL}/api/v1/app/project/{projectID}" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```text theme={null}
HTTP/1.1 204 No Content
```
## Leave a project
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/leave" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```text theme={null}
HTTP/1.1 200 OK
```
## Transfer project ownership
| Type | Name | Required | Notes |
| - | - | - | - |
| Path | `projectID` | Yes | Project identifier. |
| Body | `old_owner_id` | Yes | Current owner user ID. |
| Body | `new_owner_id` | Yes | New owner user ID; must be a project member. |
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/transfer" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"old_owner_id": "{userID}",
"new_owner_id": "{userID}"
}'
```
```text theme={null}
HTTP/1.1 200 OK
```
## Project user info
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/project/{projectID}/info/{userID}" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```text theme={null}
HTTP/1.1 200 OK
```
| Type | Name | Required | Notes |
| - | - | - | - |
| Path | `projectID` | Yes | Project identifier. |
| Body | `is_pinned` | No | Pins or unpins the project for the current user. |
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/info" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"is_pinned": true
}'
```
```text theme={null}
HTTP/1.1 200 OK
```
## Project-scoped chat
| Type | Name | Required | Notes |
| - | - | - | - |
| Path | `projectID` | Yes | Project identifier. |
| Body | `pgpt` | Yes | Chat request body. |
| Body | `artifact_ids` | No | Limits context to selected artifact IDs. |
| Body | `all_artifacts` | No | Includes all project artifacts when `true`. |
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/chat" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"all_artifacts": true,
"pgpt": {
"messages": [
{
"role": "user",
"content": [
{ "type": "text", "text": "Summarize the latest support trends in three bullets." }
]
}
],
"max_tokens": 80,
"temperature": 0.2
}
}'
```
```json theme={null}
{
"id": "inter_5a7b9c1d3e5f7a9b",
"state": "Completed"
}
```
## Errors and edge cases
* **403**: not a project member.
* **404**: project not found.
* **409**: transfer target not eligible.
# Project Members
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/workspace-api/projects/project-member
Add, update, and remove members from a project.
Use project member endpoints to control who can access a project and what role they have. Roles include `Viewer`, `Commenter`, `Editor`, `Admin`, and `Owner`.
## Basic request and response
List current members with `GET /api/v1/app/project/{projectId}/member`.
| Type | Name | Required | Notes |
| - | - | - | - |
| Path | `projectID` | Yes | Project identifier. |
| Query | `page` | No | Absolute page number to fetch, 1-based. |
| Query | `page_size` | No | Number of items per page. Default is `20`. |
| Query | `page_order` | No | `ASC` or `DESC`. Default is `ASC`. |
| Query | `after` | No | Cursor or value to paginate after. |
| Query | `before` | No | Cursor or value to paginate before. |
| Query | `first` | No | Limit to the first N items after a cursor. |
| Query | `last` | No | Limit to the last N items before a cursor. |
| Query | `total_count` | No | Include total count in the response. |
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/project/{projectID}/member?page=1&page_size=50" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
{
"data": [
{
"id": "member_1a2b3c4d5e6f",
"role": "Owner",
"user": {
"id": "user_4b7c2a1d9e5f3c8b",
"org_id": "org_2f3a9d1c7b5e4a8f",
"account_id": "acct_6c8a1f3b2d4e5f7a",
"name": "Sasha Patel",
"email": "sasha@auroralabs.com",
"state": "Active",
"roles": ["AppAdmin"],
"created_at": "2026-02-08T14:12:45Z"
},
"is_project_member": true
}
],
"has_next_page": false,
"has_previous_page": false,
"total_count": 1
}
```
## Add members
| Type | Name | Required | Notes |
| - | - | - | - |
| Path | `projectID` | Yes | Project identifier. |
| Body | `members` | Yes | Array of members to add. |
| Body | `members[].user_id` | Yes | User identifier. |
| Body | `members[].role` | Yes | `Viewer`, `Commenter`, `Editor`, `Admin`, or `Owner`. |
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/member" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"members": [
{ "user_id": "{userID}", "role": "Editor" }
]
}'
```
```json theme={null}
[
{
"id": "member_7f6e5d4c3b2a",
"role": "Editor",
"user": {
"id": "user_9d1c3b5a7f2e4c6d",
"org_id": "org_2f3a9d1c7b5e4a8f",
"account_id": "acct_6c8a1f3b2d4e5f7a",
"name": "Jordan Lee",
"email": "jordan@auroralabs.com",
"state": "Active",
"roles": ["AppMember"],
"created_at": "2026-02-07T09:20:12Z"
},
"is_project_member": true
}
]
```
## Update member roles
| Type | Name | Required | Notes |
| - | - | - | - |
| Path | `projectID` | Yes | Project identifier. |
| Body | `members` | Yes | Array of members to update. |
| Body | `members[].user_id` | Yes | User identifier. |
| Body | `members[].role` | No | `Viewer`, `Commenter`, `Editor`, `Admin`, or `Owner`. |
| Body | `members[].is_pinned` | No | Pins or unpins the project for that member. |
```bash theme={null}
curl -X PUT "https://{BASE_URL}/api/v1/app/project/{projectID}/member" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"members": [
{ "user_id": "{userID}", "role": "Admin", "is_pinned": true }
]
}'
```
```json theme={null}
[
{
"id": "member_7f6e5d4c3b2a",
"role": "Admin",
"user": {
"id": "user_9d1c3b5a7f2e4c6d",
"org_id": "org_2f3a9d1c7b5e4a8f",
"account_id": "acct_6c8a1f3b2d4e5f7a",
"name": "Jordan Lee",
"email": "jordan@auroralabs.com",
"state": "Active",
"roles": ["AppMember"],
"created_at": "2026-02-07T09:20:12Z"
},
"is_project_member": true
}
]
```
## Get or remove a member
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/project/{projectID}/member/{userID}" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
{
"id": "member_7f6e5d4c3b2a",
"role": "Admin",
"user": {
"id": "user_9d1c3b5a7f2e4c6d",
"org_id": "org_2f3a9d1c7b5e4a8f",
"account_id": "acct_6c8a1f3b2d4e5f7a",
"name": "Jordan Lee",
"email": "jordan@auroralabs.com",
"state": "Active",
"roles": ["AppMember"],
"created_at": "2026-02-07T09:20:12Z"
},
"is_project_member": true
}
```
```bash theme={null}
curl -X DELETE "https://{BASE_URL}/api/v1/app/project/{projectID}/member/{userID}" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
{
"id": "member_7f6e5d4c3b2a",
"role": "Admin",
"user": {
"id": "user_9d1c3b5a7f2e4c6d",
"name": "Jordan Lee",
"email": "jordan@auroralabs.com",
"state": "Active",
"roles": ["AppMember"],
"created_at": "2026-02-07T09:20:12Z"
},
"is_project_member": false
}
```
## Errors and edge cases
* **403**: not allowed to manage members.
* **404**: project or user not found.
# Users
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/workspace-api/users/user
Create and manage users, roles, and project access.
Use the Users API to manage people in your workspace. You can create users linked to existing accounts, update profiles and roles, and inspect related projects or artifacts.
## Basic request and response
Use `GET /api/v1/app/me` to verify your token and user context.
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/me" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
{
"id": "user_4b7c2a1d9e5f3c8b",
"org_id": "org_2f3a9d1c7b5e4a8f",
"account_id": "acct_6c8a1f3b2d4e5f7a",
"name": "Sasha Patel",
"email": "sasha@auroralabs.com",
"job_position_name": "Product Ops Lead",
"job_position_description": "Owns release coordination and analytics.",
"state": "Active",
"roles": ["AppAdmin"],
"created_at": "2026-02-08T14:12:45Z"
}
```
## List users
| Type | Name | Required | Notes |
| - | - | - | - |
| Query | `page` | No | Absolute page number to fetch, 1-based. |
| Query | `page_size` | No | Number of items per page. |
| Query | `page_order` | No | `ASC` or `DESC`. |
| Query | `after` | No | Cursor or value to paginate after. |
| Query | `before` | No | Cursor or value to paginate before. |
| Query | `first` | No | Limit to the first N items after a cursor. |
| Query | `last` | No | Limit to the last N items before a cursor. |
| Query | `total_count` | No | Include total count in the response. |
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/user?page=1&page_size=20" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
{
"data": [
{
"id": "user_4b7c2a1d9e5f3c8b",
"org_id": "org_2f3a9d1c7b5e4a8f",
"account_id": "acct_6c8a1f3b2d4e5f7a",
"name": "Sasha Patel",
"email": "sasha@auroralabs.com",
"state": "Active",
"roles": ["AppAdmin"],
"created_at": "2026-02-08T14:12:45Z"
}
],
"has_next_page": false,
"has_previous_page": false,
"total_count": 1
}
```
## Create a user
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/user" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"account_id": "{accountID}",
"role": "AppMember",
"user_info": {
"email": "sasha@auroralabs.com",
"name": "Sasha Patel",
"given_name": "Sasha",
"family_name": "Patel"
}
}'
```
```json theme={null}
{
"id": "user_4b7c2a1d9e5f3c8b",
"org_id": "org_2f3a9d1c7b5e4a8f",
"account_id": "acct_6c8a1f3b2d4e5f7a",
"name": "Sasha Patel",
"email": "sasha@auroralabs.com",
"state": "Active",
"roles": ["AppMember"],
"created_at": "2026-02-08T14:12:45Z"
}
```
## Get or update a user
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/user/{userID}" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
{
"id": "user_4b7c2a1d9e5f3c8b",
"org_id": "org_2f3a9d1c7b5e4a8f",
"account_id": "acct_6c8a1f3b2d4e5f7a",
"name": "Sasha Patel",
"email": "sasha@auroralabs.com",
"state": "Active",
"roles": ["AppMember"],
"created_at": "2026-02-08T14:12:45Z"
}
```
| Type | Name | Required | Notes |
| - | - | - | - |
| Path | `userID` | Yes | User identifier. |
| Body | `name` | No | User display name. |
| Body | `role` | No | Workspace role to assign. |
```bash theme={null}
curl -X PUT "https://{BASE_URL}/api/v1/app/user/{userID}" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"name": "Sasha Patel",
"role": "AppAdmin"
}'
```
```json theme={null}
{
"id": "user_4b7c2a1d9e5f3c8b",
"org_id": "org_2f3a9d1c7b5e4a8f",
"account_id": "acct_6c8a1f3b2d4e5f7a",
"name": "Sasha Patel",
"email": "sasha@auroralabs.com",
"state": "Active",
"roles": ["AppAdmin"],
"created_at": "2026-02-08T14:12:45Z"
}
```
## Activate or deactivate a user
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/user/{userID}/deactivate" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
{
"id": "user_9d1c3b5a7f2e4c6d",
"state": "Inactive"
}
```
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/user/{userID}/activate" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
{
"id": "user_9d1c3b5a7f2e4c6d",
"state": "Active"
}
```
## List projects for a user
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/user/{userID}/project" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
{
"data": [
{
"id": "proj_7a5c3e1b9d2f4a6c",
"name": "Customer Insights",
"goal": "Summarize weekly support trends.",
"deadline": "2026-03-01T00:00:00Z",
"visibility": "Private",
"member_count": 4,
"default_member_role": "Editor",
"default_role_enabled": true,
"project_context": "Support analytics for Q1.",
"answer_context": "Use approved templates.",
"is_pinned": true
}
],
"has_next_page": false,
"has_previous_page": false,
"total_count": 1
}
```
## Latest artifacts for a user
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/user/{userID}/latest-artifacts" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
[
{
"id": "artifact_2b4d6f8a1c3e5a7b",
"project_id": "proj_7a5c3e1b9d2f4a6c",
"name": "Q1 Support Summary",
"type": "Document",
"source": "User",
"state": "Published",
"ingest_status": "Done",
"has_content": true,
"created_at": "2026-02-08T14:30:12Z"
}
]
```
## User integrations
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/user/integrations" \
-H "Authorization: Bearer {API_TOKEN}"
-H "x-org: {org_slug}"
```
```json theme={null}
[
{
"id": "conf_8a7b6c5d4e3f2a1b",
"user_id": "user_4b7c2a1d9e5f3c8b",
"org_id": "org_2f3a9d1c7b5e4a8f",
"type": "Confluence",
"created_at": "2026-02-05T09:10:00Z",
"updated_at": "2026-02-08T10:02:11Z"
}
]
```
## Errors and edge cases
* **409**: duplicate user email or account linkage.
* **400**: invalid role.
* **404**: user not found.
# Organizations
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/workspace-api/users/user-organization
Read and update the current Workspace organization.
Organizations are the top-level container for users and projects. These endpoints operate on the organization selected by the `x-org` header.
## Basic request and response
Get the current organization with `GET /api/v1/app/organization`.
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/organization" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}"
```
```json theme={null}
{
"id": "org_2f3a9d1c7b5e4a8f",
"name": "Aurora Labs",
"slug": "aurora-labs",
"state": "Active",
"display_name": "Aurora Labs",
"context": "Enterprise R&D and analytics.",
"logo": "https://{BASE_URL}/files/org-logo.png",
"auto_join_enabled": true,
"default_role": "Viewer",
"email_regex": ".*@auroralabs.com",
"gateway_id": "gw_4b7c2a1d9e5f",
"created_at": "2026-02-08T14:12:45Z",
"member_count": null
}
```
## Update organization settings
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/organization" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"name": "Aurora Labs",
"context": "Private AI platform for product and support teams.",
"clear_context": false,
"email_regex": ".*@auroralabs.com"
}'
```
| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | No | Organization display name. Maximum 60 characters. |
| `context` | string | No | Organization context used by Workspace features. |
| `clear_context` | boolean | No | Set to `true` to remove the existing context. Defaults to `false`. |
| `logo_file_name` | string | No | Multipart logo file name. Required when uploading a logo file. |
| `logo_content_type` | string | No | Multipart logo content type. Must be PNG or JPEG. |
| `logo_content_length` | integer | No | Multipart logo size in bytes. Maximum 5 MB. |
| `fileData` | file | No | Multipart-only logo binary. |
```json theme={null}
{
"id": "org_2f3a9d1c7b5e4a8f",
"name": "Aurora Labs",
"slug": "aurora-labs",
"state": "Active",
"display_name": "Aurora Labs",
"context": "Private AI platform for product and support teams.",
"logo": "https://{BASE_URL}/files/org-logo.png",
"auto_join_enabled": true,
"default_role": "Viewer",
"email_regex": ".*@auroralabs.com",
"gateway_id": "gw_4b7c2a1d9e5f",
"created_at": "2026-02-08T14:12:45Z",
"member_count": null
}
```
## Errors and edge cases
* **401/403**: missing or invalid API token.
* **400**: invalid regex, organization name over 60 characters, unsupported logo content type, or logo larger than 5 MB.
# Embeddings
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/zylon-gpt-api/embeddings
Generate embeddings for semantic search and similarity.
Embeddings turn text into high‑dimensional vectors. Use them for semantic search, clustering, or similarity scoring across your own data.
## Prerequisites
* An API token. See [Backoffice Developer Console](/en/v1.57/developer-manual/get-started/developer-console).
* Your Zylon hostname (replace `{BASE_URL}` in the examples).
## Before you start
* **Order matters**: `data[index]` aligns with your input order.
* **Store the vectors** in your database or vector index to power search and similarity.
* **Use consistent preprocessing** (same casing and formatting) for better similarity results.
## Create embeddings
Generate embeddings with `POST /embeddings`. The `input` can be a single string or an array.
| `input` shape | When to use |
| - | - |
| Single string | One text at a time. |
| Array of strings | Batch inputs and keep output order. |
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/embeddings" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"input": "Summarize Q1 support trends in one vector."
}'
```
```json theme={null}
{
"object": "list",
"model": "private-gpt",
"data": [
{
"index": 0,
"object": "embedding",
"embedding": [
0.697265625,
0.5078125,
0.01129150390625,
0.244873046875,
-0.285888671875,
0.058135986328125,
0.01922607421875,
-0.11431884765625
]
}
]
}
```
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/embeddings" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"input": [
"Billing issues drove 38% of cases.",
"Priority bugs were resolved within 48 hours."
]
}'
```
```json theme={null}
{
"object": "list",
"model": "private-gpt",
"data": [
{
"index": 0,
"object": "embedding",
"embedding": [
-0.435546875,
-0.49169921875,
-0.48876953125,
1.41015625,
0.11114501953125,
-1.2626953125
]
},
{
"index": 1,
"object": "embedding",
"embedding": [
-0.6748046875,
0.242431640625,
-0.31396484375,
0.53955078125,
-0.84716796875,
-0.006961822509765625
]
}
]
}
```
## Errors and edge cases
* **401/403**: token missing or invalid.
* **413**: input too large.
* **400**: invalid JSON or input type.
# Handling stop reasons
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/zylon-gpt-api/handling-stop-reasons
Know why a response stopped and how to handle ZylonGPT errors.
When you call the Messages endpoint, each response includes a `stop_reason` that explains **why the model stopped**. Handling this field correctly is key to building reliable apps.
For details about `stop_reason` in the response schema, see [Messages](/en/v1.57/developer-manual/build-with-zylon/working-with-messages).
## What is `stop_reason`?
`stop_reason` is present on every **successful** response. It doesn’t mean there was an error—it tells you how the model completed its response.
Example response (truncated):
```json theme={null}
{
"id": "msg_abf981cf3f1c449eacb7a85c064ca505",
"type": "message",
"role": "assistant",
"content": [
{ "type": "text", "text": "Here’s a concise update..." }
],
"stop_reason": "end_turn",
"stop_sequence": null
}
```
## Stop reason values
When a request fails, the stop reason matches one of the error values below and the response is returned as an error envelope.
| stop\_reason | Why it happens | What to do |
| - | - | - |
| `end_turn` | The model completed its response normally. Sometimes you’ll see an empty response after tool execution if you send extra user text with a `tool_result`. | Treat as complete. If empty, send only the `tool_result` block, or add a new user message like “Please continue.” |
| `max_tokens` | The response hit your `max_tokens` limit. | Increase `max_tokens` or ask the model to continue. |
| `stop_sequence` | The model generated one of your custom stop sequences. | Treat output as complete at the boundary or adjust/remove the sequence. |
| `tool_use` | The model wants you to run a tool. | Execute the tool and return a `tool_result` block. |
| `pause_turn` | The model intentionally paused. | Resume the conversation when ready. |
| `refusal` | The model refused for safety or policy reasons. | Surface the refusal or re‑prompt with allowed content. |
| `invalid_request_error` | The request inputs are invalid (e.g., artifacts not fully ingested, missing tool config, invalid IDs). | Fix inputs and retry. |
| `permission_error` | The token lacks access to the referenced resource. | Check org/project membership and artifact visibility. |
| `request_too_large` | Input size or token count exceeds model limits. | Reduce input, chunk content, or lower context size. |
| `api_error` | An internal server error occurred. | Retry with exponential backoff. |
| `overloaded_error` | The system is temporarily overloaded. | Retry with backoff and jitter. |
# Overview
Source: https://docs.zylon.ai/en/v1.57/developer-manual/build-with-zylon/zylon-gpt-api/overview
The ZylonGPT API lets you generate responses, ingest knowledge, create embeddings, and call tools in one flow.
ZylonGPT is the model-facing API. Most apps follow a simple loop: send messages, attach or reference artifacts, generate embeddings for search, and let the assistant call tools when it needs structured data or retrieval.
Send conversation history and get structured assistant replies.
Ingest text, files, or URLs into collections for reuse.
Turn text into vectors for search and similarity.
Enable semantic search, tabular analysis, web fetch, and custom tools.
# Claude Code
Source: https://docs.zylon.ai/en/v1.57/developer-manual/get-started/claude-code-setup
Configure Claude Code CLI to work with Zylon's AI platform.
**Claude Code** is Anthropic's CLI tool for interacting with Claude models. It allows you to use Claude's capabilities directly from your terminal for development and analysis tasks.
For installation instructions, see the [official Claude Code documentation](https://claude.com/product/claude-code).
This integration was verified with **Claude Code 2.1.166** on **macOS** using **Zylon 1.57.1**. If it's not working, please check other alternatives in the [Opencode setup guide](./opencode-setup).
## Tested versions
| Zylon release | Claude Code version | Operating system | Result |
| - | - | - | - |
| 1.57.1 | 2.1.166 | macOS | Working |
## Setup Steps
Before configuring Claude Code, you need a **Gateway Token** from Zylon.
See [Token Management](./token-management) for detailed instructions on creating Gateway tokens.
Add the following to your shell configuration file (`~/.zshrc` or `~/.bashrc`):
```bash theme={null}
echo 'export ZYLON_BASE_URL="https://your-host/api/gpt"' >> ~/.zshrc
echo 'export ZYLON_API_TOKEN="your-gateway-token"' >> ~/.zshrc
echo 'export ZYLON_MODEL="default"' >> ~/.zshrc
source ~/.zshrc
```
Replace `your-host` with your Zylon instance URL and `your-gateway-token` with your actual Gateway token. The model defaults to `default`.
Never commit environment variables containing tokens to version control. Add them to your `.gitignore`.
Confirm the variables are set correctly:
```bash theme={null}
echo $ZYLON_BASE_URL
echo $ZYLON_API_TOKEN
echo $ZYLON_MODEL
```
Add the following to your shell configuration file (`~/.zshrc` or `~/.bashrc`):
```bash theme={null}
echo 'export ANTHROPIC_BASE_URL="$ZYLON_BASE_URL"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="$ZYLON_API_TOKEN"' >> ~/.zshrc
echo 'export ANTHROPIC_MODEL="$ZYLON_MODEL"' >> ~/.zshrc
source ~/.zshrc
```
Test your configuration by running:
```bash theme={null}
claude
```
If configured correctly, Claude Code will connect to your Zylon instance and be ready to assist.
## Limitations
* Images are not supported
## Troubleshooting
### Connection Errors
* Verify `ZYLON_BASE_URL` is correct and accessible
* Ensure your Gateway token is valid and not expired
* Check network connectivity to your Zylon instance
### Authentication Failures
* Confirm the token is copied correctly without extra whitespace
* Regenerate the token if it may have been compromised
* Verify the token has appropriate permissions
# Developer Console
Source: https://docs.zylon.ai/en/v1.57/developer-manual/get-started/developer-console
API token management for developers.
## Overview
Developer Console is the Backoffice area used for Gateway token management.
Tokens generated in Developer Console are the recommended option when you need one token that works across:
* Workspace API
* ZylonGPT API
* Backoffice API
It is available to:
* Accounts with **Developer** role
* Accounts with **Operator** role when they also belong to a gateway
API tokens are created within gateways and are tied to both the gateway and the account that created them.
If you only need Workspace API access, you can use the Workspace-only flow in [Workspace Token Management](/en/v1.57/developer-manual/get-started/token-management).
For role-based access details, see [Roles and Permissions](/en/v1.57/operator-manual/backoffice/roles-and-permissions).
## Create API Token
To create an API token:
1. Open **Developer Console**.
2. Select the target gateway.
3. Click **Create API Token**.
4. Enter a token name.
5. Generate the token.
6. Copy the token secret shown in the modal.
The token secret is shown only once. After closing the modal, it cannot be retrieved. Store it in a secure secret manager immediately.
## Token usage and ownership
* A token inherits the rules and configuration of its gateway.
* Token activity is linked to the account that created it.
* If a token is lost, revoke it and create a new one.
# Intro to Zylon
Source: https://docs.zylon.ai/en/v1.57/developer-manual/get-started/intro-to-zylon
Self‑hosted AI platform with Anthropic‑compatible Messages endpoints and a Workspace API.
Zylon is a self‑hosted AI platform that runs in your infrastructure. It provides Anthropic‑compatible Messages endpoints for model interaction, a Workspace API for organizations and project management, and a Backoffice API for operational workflows. In these docs, you’ll use **three APIs**:
* **ZylonGPT API**: the AI layer for model responses, tools, and content-aware chat.
* **Workspace API**: the management API for organizations, users, projects, and integrations.
* **Backoffice API**: the operational API for Backoffice workflows such as manual log retrieval.
## Choose your token flow
Use the token flow that matches your integration:
Workspace-only token flow for `/api/v1/*` endpoints.
Generate a token that works across Workspace API, ZylonGPT API, and Backoffice API.
Make your first API call with a working example.
Build AI experiences with the model-facing API.
Manage organizations, users, projects, and integrations.
Retrieve operational data such as Zylon logs.
# Opencode
Source: https://docs.zylon.ai/en/v1.57/developer-manual/get-started/opencode-setup
Install and configure Opencode CLI to work with Zylon's AI platform.
**Opencode** is an interactive CLI tool that helps developers with software engineering tasks. It provides an AI-powered coding assistant directly in your terminal, enabling you to build, debug, and maintain code with intelligent support.
For installation instructions, see the [official Opencode documentation](https://opencode.ai).
## Setup Steps
Before configuring Opencode, you need a **Gateway Token** from Zylon.
See [Token Management](./token-management#gateway-token-zylongpt) for detailed instructions on creating Gateway tokens.
Add the following to your shell configuration file (`~/.zshrc` or `~/.bashrc`):
```bash theme={null}
echo 'export ZYLON_BASE_URL="https://your-host/api/gpt"' >> ~/.zshrc
echo 'export ZYLON_API_TOKEN="your-gateway-token"' >> ~/.zshrc
echo 'export ZYLON_MODEL="default"' >> ~/.zshrc
source ~/.zshrc
```
Replace `your-host` with your Zylon instance URL and `your-gateway-token` with your actual Gateway token. The model defaults to `default`.
Never commit environment variables containing tokens to version control. Add them to your `.gitignore`.
Confirm the variables are set correctly:
```bash theme={null}
echo $ZYLON_BASE_URL
echo $ZYLON_API_TOKEN
echo $ZYLON_MODEL
```
Create the Opencode configuration directory:
```bash theme={null}
mkdir -p ~/.config/opencode
```
Create the configuration file at `~/.config/opencode/opencode.json`:
```json theme={null}
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"anthropic": {
"options": {
"baseURL": "{env:ZYLON_BASE_URL}/v1",
"apiKey": "{env:ZYLON_API_TOKEN}"
},
"models": {
"{env:ZYLON_MODEL}": {
"name": "Zylon - {env:ZYLON_MODEL}",
"limit": {
"context": 128000,
"output": 20000
}
}
}
}
}
}
```
For more details on Opencode configuration options, see the [official Opencode documentation](https://opencode.ai).
Test your configuration by running:
```bash theme={null}
opencode
```
On first launch, you'll need to switch to the Zylon model:
1. Press `Ctrl+P` to open the command palette
2. Select "Switch Model"
3. Search for and select "Zylon - Default"
Once selected, Opencode will connect to your Zylon instance and be ready to assist with coding tasks.
## Limitations
* Images are not supported
## Troubleshooting
### Connection Errors
* Verify `ZYLON_BASE_URL` is correct and accessible
* Ensure your Gateway token is valid and not expired
* Check network connectivity to your Zylon instance
### Authentication Failures
* Confirm the token is copied correctly without extra whitespace
* Regenerate the token if it may have been compromised
* Verify the token has appropriate permissions
# Quickstart
Source: https://docs.zylon.ai/en/v1.57/developer-manual/get-started/quickstart
Make your first Zylon API call in under 2 minutes.
Start with ZylonGPT to send messages, or use the Workspace API to automate org and project setup.
## Prerequisites
* A token for your target API:
* Workspace-only token flow: [Workspace Token Management](/en/v1.57/developer-manual/get-started/token-management)
* One token across Workspace API + ZylonGPT API + Backoffice API: [Backoffice Developer Console](/en/v1.57/developer-manual/get-started/developer-console)
* Your Zylon hostname (replace `{BASE_URL}` in the examples).
* For Workspace API: an account and an organization created in the workspace.
## My first Zylon call
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/gpt/v1/messages" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"model": "default",
"max_tokens": 64,
"messages": [
{ "role": "user", "content": "Write a one-sentence product description for Zylon." }
]
}'
```
Example response (your `id` and timestamps will differ):
```json theme={null}
{
"id": "msg_d88cec8ffdf344dcafddb72026ead6be",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"start_timestamp": "2026-02-06T13:16:10.412540Z",
"stop_timestamp": "2026-02-06T13:16:10.543884Z",
"text": "Zylon is a private AI platform for building secure, tool-using assistants and workflows."
}
],
"model": "private-gpt",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 93,
"output_tokens": 18
}
}
```
Set `stream: true` to receive **Server-Sent Events (SSE)**.
```bash theme={null}
curl -N -X POST "https://{BASE_URL}/api/gpt/v1/messages" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{
"model": "default",
"stream": true,
"max_tokens": 32,
"messages": [
{ "role": "user", "content": "Give a three-word tagline for a productivity app." }
]
}'
```
Example streamed events (truncated):
```text theme={null}
event: message_start
data: {"type":"message_start","message":{"id":"msg_b55d29718361410bad4f80f8f67c6b72","type":"message","role":"assistant","content":[],"model":"private-gpt","usage":{}}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"block_id":"block_019c331ac11375cea03f7e0fb7a2a044","delta":{"type":"text_delta","text":"Focus"}}
event: message_stop
data: {"type":"message_stop"}
```
Workspace requests under `/api/v1/app/*` require the `x-org` header to target the correct organization. You can send either the organization slug (recommended) or the organization ID. In the examples below, use `x-org: {org_slug}`.
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/auth/login" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"email": "{username}",
"password": "{password}"
}'
```
Example response:
```json theme={null}
{
"id": "acct_6c8a1f3b2d4e5f7a",
"email": "sasha@auroralabs.com",
"provider": "Credentials",
"roles": ["AppAdmin"]
}
```
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"name": "Customer Insights",
"goal": "Summarize weekly support trends.",
"deadline": 1709337600,
"visibility": "Private"
}'
```
Example response:
```json theme={null}
{
"id": "proj_7a5c3e1b9d2f4a6c",
"name": "Customer Insights",
"visibility": "Private"
}
```
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/artifact" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-F 'type=Document' \
-F 'name=Q1 Support Summary' \
-F 'props={
"content_type":"text/plain",
"file_name":"q1-support-summary.txt"
};type=application/json' \
-F 'fileData=@./q1-support-summary.txt;type=text/plain'
```
Example response:
```json theme={null}
{
"id": "artifact_2b4d6f8a1c3e5a7b",
"project_id": "proj_7a5c3e1b9d2f4a6c",
"name": "Q1 Support Summary",
"type": "Document",
"state": "Ready",
"ingest_status": "Done",
"has_content": true
}
```
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/project/{projectID}/thread" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"name": "Weekly Support Brief",
"visibility": "Private"
}'
```
```bash theme={null}
curl -X POST "https://{BASE_URL}/api/v1/app/thread/{threadID}/interaction" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}" \
-H "Content-Type: application/json" \
-d '{
"thread_id": "{threadID}",
"artifact_ids": ["{artifactID}"],
"pgpt": {
"messages": [
{
"role": "user",
"content": [
{ "type": "text", "text": "Summarize the artifact in three bullets." }
]
}
],
"max_tokens": 96,
"temperature": 0.2
}
}'
```
Example response:
```json theme={null}
{
"id": "inter_5a7b9c1d3e5f7a9b",
"state": "Completed"
}
```
## Next steps
Learn the Messages, Artifacts, and Tools APIs.
Manage orgs, users, projects, and integrations.
## Troubleshooting
* **401/403**: your token is invalid, expired, or issued for the wrong flow. Use [Workspace Token Management](/en/v1.57/developer-manual/get-started/token-management) for Workspace-only access, or [Backoffice Developer Console](/en/v1.57/developer-manual/get-started/developer-console) for a cross-API token.
* **404**: Check your base URL. For ZylonGPT, use `https://{BASE_URL}/api/gpt/v1/`.
* **400 (model not found)**: Use `"model": "default"` unless you’ve been given a specific model name.
* **405**: You’re using the wrong method. `/messages` is `POST`.
# Token Management
Source: https://docs.zylon.ai/en/v1.57/developer-manual/get-started/token-management
Choose the right token flow: Backoffice cross-API token or Workspace-only token.
Use this page to pick the right token flow for your integration.
## Which token do I need?
Routes `/api/v1/*`.
Automate Workspace operations — create projects, manage users, interact with ingested files, and more.
Routes `/api/gpt/v1/*`.
Call the ZylonGPT API directly, the same way you'd use the Anthropic API.
This flow is for **Workspace API** access under `/api/v1/*`.
Workspace token flow does **not** issue tokens for direct ZylonGPT API calls under `/api/gpt/v1/*`.
### Create a Workspace API token
1. Sign in to Workspace as an account that can manage API tokens.
2. Click the organization logo and open **API Tokens**.
3. Click **Create API Token**, provide a name, and save.
4. Copy and store the token value immediately. It is shown once.
![]()
![]()
### Verify token access
Workspace endpoints under `/api/v1/app/*` require the `x-org` header.
```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/me" \
-H "Authorization: Bearer {API_TOKEN}" \
-H "x-org: {org_slug}"
```
```json theme={null}
{
"id": "user_4b7c2a1d9e5f3c8b",
"org_id": "org_2f3a9d1c7b5e4a8f",
"account_id": "acct_6c8a1f3b2d4e5f7a",
"name": "Sasha Patel",
"email": "sasha@auroralabs.com",
"state": "Active",
"roles": ["AppAdmin"],
"created_at": "2026-02-08T14:12:45Z"
}
```
### Revoke a Workspace token
Open **API Tokens** and click the trash icon on the token row.
![]()
This flow grants access to the **ZylonGPT API** under `/api/gpt/v1/*`, as well as Workspace and Backoffice APIs.
### Create a Gateway token
1. Open **Developer Console**.
2. Select the target gateway.
3. Click **Create API Token**.
4. Enter a token name.
5. Generate the token.
6. Copy the token secret shown in the modal.
The token secret is shown **only once**. After closing the modal, it cannot be retrieved. Store it in a secure secret manager immediately.
# Getting Started
Source: https://docs.zylon.ai/en/v1.57/operator-manual/installation/overview
Choose your installation mode based on your security and connectivity needs
Zylon supports three installation modes. Choose based on your network environment and security requirements.
## Quick Comparison
| | Online | Semi-Airgap | Full-Airgap |
| - | - | - | - |
| **Installation Type** | Online | Online | Offline |
| **Operational Connectivity** | Full | Restricted/Zero | Restricted/Zero |
| **Use Case** | Standard deployments | Controlled network access | Offline installation & Maximum security |
| **Complexity** | Simple | Moderate | Complex |
| **Installation Time** | 30-90 min | 1-2 hours | 2-3 hours |
| **Update Time** | 15-40 min | 30-60 min | 1-2 hours |
| **Update Downtime** | Rare | Rare | Always (15-60 min) |
***
## Installation Modes
### Online Installation
**Use when**: Standard deployments with full internet access
**How it works**: Server downloads packages and images directly from official repositories.
**Key characteristics**:
* Automated setup and updates
* Minimal downtime for updates
* Standard security posture
**Installation Guide** → [Online Installation](/en/v1.57/operator-manual/installation/online)
### Semi-Airgap Installation
**Use when**: Networks with controlled internet access via proxy/firewall
**How it works**: Online installation through whitelisted domains and proxy configuration.
**Key characteristics**:
* **Installation**: Online (requires internet connectivity)
* **Operation**: Can run with restricted/zero connectivity
* Requires open domains and ports during installation/updates
* Minimal downtime for updates
* Proxy support
**Installation Guide** → [Semi-Airgap Installation](/en/v1.57/operator-manual/installation/semi-airgap)
### Full-Airgap Installation
**Use when**: Offline installation required, no internet access during setup
**How it works**: Transfer 70-100 GB bundles from online machine via offline media to target server.
**Key characteristics**:
* **Installation**: Offline (no internet required on target server)
* **Operation**: Can run with restricted/zero connectivity
* Requires two linux machines (online and offline)
* Manual update process (download, transfer, apply)
* Always requires downtime (15-60 min)
**Installation Guide** → [Airgap Installation](/en/v1.57/operator-manual/installation/airgap)
***
## Installation Steps
Select the mode matching your security policy and network environment.
Follow the guide for your chosen mode. All modes use the Zylon CLI installer.
Configure [AI Presets](/en/v1.57/operator-manual/ai-presets), set up [backups](/en/v1.57/operator-manual/operations/backup), and review the [User Manual](/en/v1.57/user-manual/quick-start-guide).
# How to use this manual
Source: https://docs.zylon.ai/en/v1.57/operator-manual/overview
Welcome to Zylon’s Operations Manual!
If you are new to [Zylon](https://www.zylon.ai/), you have probably landed here because someone
at your organization wants you to be part of the process of adopting Private AI.
Zylon is an enterprise AI platform delivering private generative AI and on-premise AI software for regulated industries, enabling secure deployment inside enterprise infrastructure without external cloud dependencies.
Because Zylon runs full on-premise, this document provides comprehensive
instructions for installing, configuring, and maintaining Zylon platform and
its collaborative workspace in your private on-premise infrastructure.
You can see in the following image an overview of the most important systems
that would be deployed as part of your Zylon installation:
![image]()
This guide covers essential topics including system requirements, driver installation,
network configuration, SSL setup, and integration with OpenID.
You'll also find procedures for maintenance tasks like backups and troubleshooting.
Security guidance focuses on protecting and hardening the platform. For auditability, governance, traceability, evidence preservation, and AI accountability, see [Auditability & AI Governance](/en/v1.57/operator-manual/auditability-ai-safety/overview).
To get Zylon up and running follow the steps of the operations manual step by step.
Some of them may be skipped depending on the installation type you choose, in any case,
it will be stated if the step can be skipped and why.
Let’s begin your Zylon journey to adopt Private AI!
# Welcome to Zylon
Source: https://docs.zylon.ai/en/v1.57/overview
Zylon is an enterprise AI platform delivering private generative AI and on-premise AI software for regulated industries, enabling secure deployment inside enterprise infrastructure without external cloud dependencies.
## Zylon Users
Are you a Zylon user? Check out these resources to get started.
Learn what Zylon Workspace is and how it transforms your company knowledge into productivity gains
Quick answers to common questions when starting with Zylon Workspace
Get productive in 15 minutes with essential workflows and examples
## Developers
Head over to the developer documentation to work with Zylon's APIs and build custom agents and workflows.
Get started with Zylon's high-level and low-level APIs
Direct access to AI capabilities with OpenAI-compatible endpoints
Programmatic access to projects, knowledge bases, and collaborative features
## Administrators
Find the resources you need to deploy Zylon, connect it to your data, and manage everything.
Understand how to set up Zylon for your organization with our complete deployment guide
Deploy Zylon on-premise in less than 3 hours with single command installation.
Understand the hardware requirements to run Zylon platform on-premise
Review auditability, traceability, evidence preservation, governance, and AI accountability capabilities
## Key Benefits of Zylon
**Complete Data Sovereignty**: Your data never leaves your premises. Zylon runs entirely on-premise, including AI models, ensuring total control and compliance with regulatory requirements.
**Governance and Audit Readiness**: Zylon documents auditability, AI governance, retention, evidence collection, and control-mapping guidance separately from core platform security.
**Unlimited AI Usage**: Unlike cloud services that charge per token, Zylon provides unlimited AI interactions with fixed, predictable costs.
**Enterprise Ready**: Deploy in under 3 hours on any infrastructure. No vendor lock-in, full customization, and white-label capabilities.
***
**Need immediate help?** Contact our support team at [dev@zylon.ai](mailto:dev@zylon.ai) or [request a demo](https://cal.com/zylon/demo?source=docs) to see Zylon in action.
# Adding Company Context
Source: https://docs.zylon.ai/en/v1.57/user-manual/adding-company-context
Manage the organization-level context in the admin area.
Adding relevant company context **is a quick and effective way to customize your company's Private AI**. Include information about the company: what it does, the general purpose of the company's AI and any other relevant information like acronyms or company-specific terms.
The **AI will take that context into account in every interaction across every project**.
## Where to find it
Click on the **Workspace name** in the top right, and select **Company Context**.
![]()
## What not to use it for
Changing the **assistant name** or other instance-level settings is **not done** here. That is a **platform/instance configuration** task. Refer to your Zylon administrator or review the Operations Manual.
# Adding custom instructions
Source: https://docs.zylon.ai/en/v1.57/user-manual/adding-custom-instructions
Provide project-specific instructions used in every chat in the project.
Each project can define **custom instructions** that the AI uses on **every interaction in that project**. These augment, rather than replace, the organization-wide company context.
Open **Project Settings**, write your instructions in the single **Instructions** field, and save the project settings.
Use this field for project-specific guidance such as:
* what this project is for
* who it serves
* important acronyms or domain context
* preferred response style or language
The maximum size of this field is controlled by your operator through `feature.maxInstructionsLength` in `/etc/zylon/zylon-conf.yaml`. The default limit is `4000`, and the same limit is enforced in both the Workspace UI and the API. For operator-side configuration, see [Project custom instructions](/en/v1.57/operator-manual/configuration/features/feat-project-custom-instructions).
![]()
## Advanced Settings
Project settings also include two advanced toggles:
![]()
* **Citations**: Enables or disables citations in Zylon chat responses for that project.
* **System prompt**: Keeps or removes Zylon's default prompt layer. This prompt cannot be edited from the UI, only removed.
These settings change how Zylon responds. Changing them can reduce answer quality, reduce traceability, or cause responses to fail, so use them carefully.
> **Behavior:** Custom instructions apply at the project level and shape how Zylon responds in that project together with the organization-wide company context.
# Answer in bulk
Source: https://docs.zylon.ai/en/v1.57/user-manual/agent-flows/answer-in-bulk
Ask many questions at once and get a table of answers with citations.
Paste a list of **questions** and point the flow at relevant files/folders in the Knowledge Base. The output is a **table** of **Question → Answer** with **citations** to the exact source passages.
* Ideal for RFPs, due diligence, vendor questionnaires.
* Export options include document/table formats (e.g., CSV).
# Generate draft
Source: https://docs.zylon.ai/en/v1.57/user-manual/agent-flows/generate-draft
Create a new document that follows the tone and content of selected sources.
Select reference files (e.g., prior ads, policies, specs) and describe the **draft you want**. The agebt flow inferes the required sections and creates a new document drawing on your sources and instructions.
> After generation, co‑edit with teammates and use **Inline AI** to iterate.
# Open blank page
Source: https://docs.zylon.ai/en/v1.57/user-manual/agent-flows/open-blank-page
Start from scratch and optionally use AI to help you write.
Create an empty document and **use AI inline** to compose sections. You can ground prompts in the **project Knowledge Base** to pull accurate facts and references.
# Read and extract
Source: https://docs.zylon.ai/en/v1.57/user-manual/agent-flows/read-and-extract
Define topics and extract all relevant passages across long documents, with citations.
For long, compliance‑sensitive or spec‑heavy documents (e.g., RFPs), define the **topics** to extract (e.g., *mobile app requirements*, *payment terms*, *entity names*) and point it to the set of documents to be analyzed. The flow works as follows:
1. **Reads the full document/s**.
2. **Highlights** relevant sentences per topic.
3. Produces a structured list with **exact quotes** and **citations** to the source locations.
4. Lets you **prune** or **post‑process** (e.g., “summarize into five points”).
> This is an advanced flow but extremely effective for structured reviews and downstream analysis.
# Summarize file
Source: https://docs.zylon.ai/en/v1.57/user-manual/agent-flows/summarize-file
Produce a comprehensive summary of long documents or folders.
Choose one or more files/folders from the project KB and request a **summary**. The flow reads the **entire content**, taking the time needed for completeness.
* Provide guidance (e.g., “make it an onboarding guide”, “level of detail: moderate”).
* Edit the result and use **Inline AI** to refine structure/format.
# Block Resource Downloads
Source: https://docs.zylon.ai/en/v1.57/user-manual/block-resource-downloads
Control whether users can download uploaded Knowledge Base files and AI-generated resources.
Zylon lets administrators control downloads separately for **uploaded Knowledge Base files** and **AI-generated resources**. This helps organizations meet data-handling, compliance, and information-governance requirements while continuing to let users work with the content in Zylon.
Blocking downloads reduces the ways users can export content from Zylon; it does not remove their access to content they are otherwise allowed to view. Consider this setting alongside project membership, roles, and your organization's data-handling policies.
![Workspace Settings showing the Advanced Settings download controls.]()
## Enable or block downloads
Only Workspace administrators can change these settings.
1. Select the **Workspace name** in the upper-right corner.
2. Select **Settings**.
3. Under **Advanced Settings**, set either or both download controls.
4. Select **Save**. The change applies across the Workspace.
The settings are enabled by default. Turn a setting off to block that category of downloads.
## What each setting controls
Turn on the setting shown in the table to allow the corresponding download action. Turning it off blocks that action throughout the Workspace. **✓** means the setting controls the action; **✕** means it does not.
| Download action | **Allow to download files in the Knowledge Base** | **Allow to download generated content** |
| - | - | - |
| Download an original file retained in a Knowledge Base | ✓ | ✕ |
| Download a source file from a chat citation or source panel | ✓ | ✕ |
| Download a source file from an AI Document's source details | ✓ | ✕ |
| Open a PDF preview that requires the original Knowledge Base file | ✓ | ✕ |
| Download an AI-generated file from chat | ✕ | ✓ |
| Download a generated code block, CSV, or table result from chat | ✕ | ✓ |
| Export an AI Document as PDF or DOCX | ✕ | ✓ |
Users can still view processed Knowledge Base content, citations, AI responses, and AI Documents when the relevant download setting is disabled, provided they otherwise have access. Non-download actions, such as reporting an issue, also remain available.
## Important considerations
* These are Workspace-wide controls. They apply to all projects in the Workspace once the settings are saved.
* Enabling Knowledge Base file downloads does not grant extra access. Users must also have access to the project and the relevant **Download Files** project permission.
* Disabling a setting also blocks the corresponding download actions through the Zylon API; it is not limited to hiding buttons in the Workspace interface.
* Blocking downloads does not change access to external links supplied by a connected source. Apply the source system's own sharing and download policies where needed.
* Review the settings regularly with your security or compliance team, especially before adding sensitive source material or enabling document exports.
# Claromentis connector
Source: https://docs.zylon.ai/en/v1.57/user-manual/connectors/claromentis
Import folders and files from Claromentis and keep them in sync on demand.
You can import **files and folders** from Claromentis that you have access to. After importing, use the **Update** buttom (within the 3 dots menu) to **sync** with the source:
* Detects **content changes** in files.
* Adds **new files** and **removes** deleted ones.
* Reflects **moves/renames** so the structure mirrors Claromentis.
> Everyone with access to the Project will have access to the files and folders you connect to the project, independently of the original permissions in the File System.
![]()
![]()
![]()
Check how to enable the connector in the [Operator Manual](/en/v1.57/operator-manual/knowledge-base/claromentis)
# Confluence connector
Source: https://docs.zylon.ai/en/v1.57/user-manual/connectors/confluence
Import folders and files from Confluence and keep them in sync on demand.
You can import **Spaces** from Confluence that you have access to. After importing, use the **Update** buttom (within the 3 dots menu) to **sync** with the source:
* Detects **content changes** in files.
* Adds **new files** and **removes** deleted ones.
* Reflects **moves/renames** so the structure mirrors Confluence Space.
> Everyone with access to the Project will have access to the files and folders you connect to the project, independently of the original permissions in Confluence.
![]()
![]()
Check how to enable the connector in the [Operator Manual](/en/v1.57/operator-manual/knowledge-base/confluence)
# Confluence Server connector
Source: https://docs.zylon.ai/en/v1.57/user-manual/connectors/confluence-server
Import pages from an on-premise Confluence Server / Data Center instance and keep them in sync on demand.
You can import **Spaces** from a **Confluence Server / Data Center** instance that you have access to.
After importing, use the **Update** button (within the 3-dots menu) to **sync** with the source:
* Detects **content changes** in pages.
* Adds **new pages** and **removes** deleted ones.
* Reflects **moves and renames**, keeping the structure in sync with the Confluence Space hierarchy.
Confluence Server does not use folders.
Instead, **pages and their child pages** are used to recreate the hierarchy.
> Everyone with access to the Project will have access to the pages you connect, independently of the original permissions in Confluence.
![]()
![]()
Check how to enable the connector in the
[Operator Manual](/en/v1.57/operator-manual/knowledge-base/confluence-server)
# File System Connector
Source: https://docs.zylon.ai/en/v1.57/user-manual/connectors/file-system
Import folders and files from an SMB server and keep them in sync on demand.
You can import **files and folders** from a SMB based file system that you have access to. After importing, use the **Update** buttom (within the 3 dots menu) to **sync** with the source:
* Detects **content changes** in files.
* Adds **new files** and **removes** deleted ones.
* Reflects **moves/renames** so the structure mirrors the structure of the File System.
> Everyone with access to the Project will have access to the files and folders you connect to the project, independently of the original permissions in the File System.
![]()
![]()
![]()
Check how to enable the connector in the [Operator Manual](/en/v1.57/operator-manual/knowledge-base/file-system)
# Google Drive connector
Source: https://docs.zylon.ai/en/v1.57/user-manual/connectors/google-drive
Import Google Drive files and folders into a project knowledge base.
You can import **files or folders** from **My Drive** and **Shared with me** that your Google account can access. After importing, use **Update** from the three-dot menu to sync the source:
* Detects content changes in files.
* Adds new files and removes deleted files.
* Reflects moves and renames so the project structure mirrors Google Drive.
> Everyone with access to the project can access the Google Drive files and folders you connect, independently of the original Google Drive permissions.
\[Placeholder: Add a screenshot of the Google Drive sign-in and Picker flow.]
Ask your administrator to configure the connector, or follow the [Google Drive integration setup](/en/v1.57/operator-manual/knowledge-base/google-drive).
# SharePoint connector
Source: https://docs.zylon.ai/en/v1.57/user-manual/connectors/sharepoint
Import folders and files from SharePoint and keep them in sync on demand.
You can import **files or folders** from SharePoint that you have access to. After importing, use the **Update** buttom (within the 3 dots menu) to **sync** with the source:
* Detects **content changes** in files.
* Adds **new files** and **removes** deleted ones.
* Reflects **moves/renames** so the structure mirrors SharePoint.
> Everyone with access to the Project will have access to the SharePoint files and folders you connect to the project, independently of the original permissions in SharePoint.
![]()
Refer to your administrator or review the Operator Manual to learn how to configure your SharePoint integration.
# Creating a project
Source: https://docs.zylon.ai/en/v1.57/user-manual/creating-a-project
Create a new project and understand where it lives by default.
Projects are the workspaces where chats, AI Documents, and a project-specific knowledge base live. When you create a project, it is **created in your private space by default** (visible only to you).
## Steps
1. Go to the sidebar and select New project.
2. Enter a name.
3. Create. You will be redirected to the project and the project will appear in the project list.
> **Tip:** You can **pin** projects to keep personal shortcuts. Pinning is a per‑user convenience and does not affect other users.
# Engagement Analytics
Source: https://docs.zylon.ai/en/v1.57/user-manual/engagement-analytics
Admin‑only, aggregated view (usage dashboard) to understand adoption over time.
The **Usage Dashboard** is used to understand **engagement**. It is **admin‑only** and shows **aggregated** information.
## What you can see
* Activity across the workspace (e.g., **queries**, **chats**, **projects**, **AI Documents**, **documents linked**).
* **Temporal** views: how people is engaging over time.
* **Top users and projects** list of top N users and projects via dropdown.
![]()
![]()
![]()
> Combining **Usage Dashboard** with **Audit Logs** gives a fuller picture of adoption and behavior.
Engagement Analytics is designed to **demonstrate value** and support enablement—without exposing the content of individual interactions.
# First Day FAQs
Source: https://docs.zylon.ai/en/v1.57/user-manual/first-day-faqs
Quick answers to common questions when starting with Zylon Workspace
## Getting Started
**How do I access Zylon Workspace?**
Your IT administrator will provide you with a login URL and credentials. Zylon typically integrates with your company's Single Sign-On (SSO) system, so you may be able to use your regular work credentials.
If you can't access the system, contact your IT administrator for help.
**What should I do first?**
1. **Create your first project** - Start with something simple like "Personal Research"
2. **Upload a few documents** or connect to a SharePoint folder you use regularly
3. **Try asking a question** about the documents you uploaded
4. **Review the response and citations** to understand how Zylon works
The [Quick Start Guide](/en/v1.57/user-manual/quick-start-guide) walks through this process step by step.
**Do I need training to use Zylon?**
No formal training is required. Zylon is designed to be intuitive - if you can use ChatGPT, you can use Zylon. The interface is conversational and user-friendly.
However, reviewing the [Beginner's Guide to Chat](/en/v1.57/user-manual/querying-company-documents) will help you get better results faster.
## Projects and Knowledge
**What is a project and why do I need one?**
Projects are how you organize your work in Zylon. Each project has:
* Its own knowledge base (connected documents)
* Custom instructions for how AI should behave
* Specific team members with different access levels
Think of projects like folders, but for AI work. You might have separate projects for customer support, research, or compliance work.
**Can I see other people's projects?**
Only if they specifically share them with you. Projects are private by default. When someone shares a project with you, you'll see it in your project list with your assigned role (Viewer, Contributor, or Admin).
**What documents can I upload?**
Zylon supports common business file formats:
* PDFs (must be text-searchable, not just scanned images)
* Microsoft Word documents (.docx, .doc)
* Excel spreadsheets (.xlsx, .xls)
* PowerPoint presentations (.pptx, .ppt)
* Plain text files (.txt, .csv)
You can also connect to SharePoint, Confluence, and other systems.
**How long does it take to process documents?**
Most documents process within 2-5 minutes after upload. Larger files or many files at once may take longer. You'll see a processing indicator, and you can use the documents once processing is complete.
## Using the Chat Assistant
**How do I ask good questions?**
**Be specific**: Instead of "tell me about customers," try "what are the top 3 customer complaints from last quarter?"
**Include context**: "According to our sales policies, what's the discount approval process for enterprise deals?"
**Reference timeframes**: "Show me budget changes since January 2024"
The AI works best when you give it clear, detailed questions.
**How do I know if the AI's answer is accurate?**
Always check the citations! Every response includes numbered citations that link directly to the source documents. Click on these to verify the information.
![]()
If something seems wrong, check the source document to see the full context.
**What's the difference between Personal and Collaborative chats?**
**Personal chats**: Only you can see the conversation. Good for sensitive research or preliminary analysis.
**Collaborative chats**: Visible to all project members. Others can see your questions and add their own. Great for team discussions and shared research.
## Common Issues
**Why can't Zylon find information I know exists?**
Check these common causes:
* The document might still be processing (wait a few minutes)
* The document isn't connected to your current project
* Try rephrasing your question with different keywords
* Make sure the document is text-searchable (not a scanned image)
If the problem persists, contact your administrator.
**The AI response seems incomplete or wrong**
* Check if you're using the right project with relevant documents
* Try asking more specific questions
* Look at the citations to see what sources were used
* Remember that AI provides suggestions, not definitive answers - always use your professional judgment
**I accidentally shared a project with the wrong people**
If you're a project Admin, go to project settings and remove the incorrect members. If you're not an Admin, contact the person who created the project or your IT administrator.
## Data and Privacy
**Is my data safe in Zylon?**
Yes. Zylon runs entirely on your company's infrastructure. Your data never leaves your premises, and there are no external API calls to cloud services.
All interactions are logged for audit purposes, and access is controlled by your IT administrators.
**Can I delete documents or conversations?**
Yes, you are in control of the documents you connect to the knowledge base and the content you generate.
**Who can see my chat conversations?**
* **Personal chats**: Only you
* **Collaborative chats**: All members of the project
* **Administrators**: May have access for audit and compliance purposes
Check your organization's policies for specific details about data retention and access.
# Group chats
Source: https://docs.zylon.ai/en/v1.57/user-manual/group-chats
Start collaborative chats in a project and convert private chats when needed.
When starting a chat in a project, choose:
* **Personal** — private to you (shows a lock icon).
* **Collaborative** — visible to all project members; teammates can reply and continue the thread.
You can **convert a private chat to collaborative** later. This action **cannot be undone**. Collaborative chats are discoverable via **Search** by members who have access to the project.
# Inline AI in the editor
Source: https://docs.zylon.ai/en/v1.57/user-manual/inline-ai-in-editor
Use AI on selections to improve or generate content, optionally grounded in your knowledge base.
Select text in a flow document or type '/' to invoke AI. Use it to **improve format**, **rewrite**, or **generate** content. You can choose whether the AI should **use the project’s knowledge base** or answer generically.
* Example: “Improve the format” (don’t use Knowledge Base).
* Example: “Insert more details around our Android app requirements” (use Knowledege Base to retrieve the customer support docs and insert the facts).
# Linking knowledge bases
Source: https://docs.zylon.ai/en/v1.57/user-manual/linking-knowledge-bases
Reuse content from other projects without re‑ingesting.
To **reuse** content from the Knowledge Base of another project **without duplicating** it:
1. In **Upload files**, choose **Link from another project**.
2. Select the **source project**, then link either its **entire Knowledge Base** or specific **folders**.
3. Linked content is **available immediately** (no re‑ingestion).
**Updates propagate** from the original project automatically—linked folders/files stay in sync with their source.
> **Tip:** Use folders to scope chats. When you start a chat you can target the **entire Knowledge Base** or a **specific folder** to improve accuracy.
# Managing Organization Skills
Source: https://docs.zylon.ai/en/v1.57/user-manual/managing-organization-skills
Admin-only. Build a shared library of Skills that any project in your organization can use.
**Skills** are ready-made instruction packs that teach Zylon's assistant how to handle a specific task the same way every time — for example, formatting a spreadsheet a certain way, or summarizing a report with a fixed structure. As an admin, you can publish Skills at the **organization level** so every project can reuse them, instead of every team building its own from scratch.
Want to know what a Skill actually is and how people use one in chat? See [Introduction to Skills](/en/v1.57/user-manual/skills/introduction-to-skills).
***
## Where to find it
Go to **Admin → Skills**. You'll see every Skill currently published to your organization, along with its description and who created it.
![Organization skills list in the admin panel]()
***
## Adding an organization Skill
1. Click **New Skill**.
2. Drag a Skill file onto the dropzone (a `.zip`, `.skill`, or `SKILL.md` file), or click **Add Files** to pick one from your device.
3. Review the name and description Zylon detected from the file.
4. Click **Install** to publish it to the organization.
![Uploading a skill to the organization library]()
Only upload Skills from sources you trust. A Skill's instructions run automatically whenever it's used, so review its contents before publishing it for the whole organization.
***
## Removing a Skill
Open the **⋯** menu next to a Skill and select **Delete**. Keep in mind that removing an organization Skill also removes it from every project that has installed it.
***
## What project teams can do with it
Once a Skill is published here, project admins can add it to their own project in a couple of clicks — see [Installing an organization Skill](/en/v1.57/user-manual/skills/installing-from-organization). You don't need to configure anything per project; publishing it here is enough to make it available everywhere.
# First steps in n8n
Source: https://docs.zylon.ai/en/v1.57/user-manual/n8n
n8n is an open-source workflow automation tool that allows users to connect various applications and services to automate repetitive tasks.
Zylon includes a preconfigured n8n instance ready to use, making it easy for users to create and manage automated workflows directly from the
Zylon platform.
![n8n MCP Integration with Zylon]()
If you haven't configured n8n in your Zylon instance yet, you can check the n8n configuration manual [here](/en/v1.57/operator-manual/configuration/n8n).
# Getting Started
Once n8n is configured in your Zylon instance, you can access the n8n web interface, which is available by default at the following URL:
`https://n8n.`.
It is possible that a custom domain was configured for n8n during the installation process.
## Creating an Account in n8n
The first time you access the n8n instance, you'll be asked to create an administrator account. This account will have full privileges to manage users, configure global settings, and administer all workflows in the instance.
**Steps to create the administrator account:**
1. Go to `https://n8n./n8n`
2. Complete the registration form
3. Accept the terms of use
4. Click "Create account"
## Creating New Users
Additional users can be invited to the n8n instance through invitation links.
Each user can have one of two roles: **Administrator** (full access) or **Member** (limited access to assigned workflows and credentials).
Only administrators can create new users in n8n.
**Steps to invite users:**
1. Click the user icon (bottom left corner)
2. Select **Settings > Users**
3. Click the **"Invite"** button
4. Enter the new user's email address
5. Select the appropriate role:
* **Administrator**: Full access to configuration, users, and all workflows
* **Member**: Access only to shared workflows and credentials
6. Click **"Create invite link"**
7. Share the invitation link with the new user
# Connecting to Zylon Chat Model
To connect n8n with Zylon's chat models, you can use the Anthropic node that comes integrated with n8n, as Zylon is compatible with Anthropic nodes in n8n, enabling seamless integration.
The prerequisites are:
* Having a Zylon API token (see [Backoffice Developer Console](/en/v1.57/developer-manual/get-started/developer-console))
Once you have the prerequisites, you can proceed to configure n8n:
### Credential Configuration
1. Navigate to the Credentials section in n8n
2. Create a new credential by selecting "Anthropic"
3. Configure the following options:
* **Name**: Descriptive name for the credential (e.g., Zylon) (The name is modified in the upper left corner of the form)
* **API Key**: The Zylon API token
* **Base URL**: The Zylon API URL, which is generally `https:///api/gpt`
4. Save the credential (if everything goes well, "Connection tested successfully" will appear)
### Creating a Simple Workflow
Now that we have the credentials, we can create a simple workflow that uses Zylon's chat model.
1. Navigate to the Workflows section in n8n
2. Create a new workflow
3. Add an "Anthropic Chat Model" node to the workflow
4. Configure the node with the following options:
* **Credentials**: Select the Anthropic credential we created earlier
* **Model**: Select "By ID" and enter "default" to use the default model in your Zylon instance.
Now you can use Zylon's chat model in n8n to create automated workflows.
# Using MCP from Chat to Connect with n8n Workflows
Zylon also allows you to use MCP (Model Call Protocol) from the chat to interact with n8n workflows.
This enables users to execute workflows directly from the chat interface.
To do this, you must first create a workflow in n8n that is designed to be called from MCP.
## Creating a Workflow in n8n for MCP
For security, configure all MCP Server Trigger nodes with **Bearer** authentication and use dedicated Bearer credentials with strong tokens.
1. Navigate to the Workflows section in n8n
2. Create a new workflow
3. Add an "MCP Server Trigger" node to the workflow
4. Set **Authentication** to **Bearer** and create or select a Bearer credential
* **Name**: Use a descriptive name (e.g., Zylon MCP)
* **Bearer Token**: Generate a long, secure token and save it—you will need it when connecting from Zylon
5. Copy the "Production URL" generated in the MCP Server Trigger node and configure the remaining options according to your needs
6. Add tools to the MCP Server Trigger node to define the actions you want the workflow to perform when called from Zylon chat
7. Go back to the workflow main page and activate the workflow by clicking the toggle button in the upper right corner
More information about the MCP Server Trigger node in n8n can be found [here](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-langchain.mcptrigger/).
## Calling the Workflow from Zylon Chat Using MCP
Once the workflow is configured and tested in n8n, we can call it from Zylon chat using MCP.
1. Open the chat interface in Zylon
2. Select a project and navigate to the connectors section
3. Click "New Connector" and select "Add MCP Server"
4. Configure the following options:
* **Name**: Descriptive name for the connector (e.g., n8n MCP)
* **MCP Server URL**: Paste the "Test URL" we copied from the MCP Server Trigger node in n8n
* **Authentication**: Select **Bearer**
* **Bearer Token**: Paste the secure token you created in n8n for this connector
5. Click "Connect" (if an error occurs, make sure the workflow in n8n is active)
6. Navigate to the chat section and select the MCP connector we just created
7. Now we can send messages in the chat that will call the workflow in n8n through MCP
## Additional documentation about MCP and its use in Zylon can be found [here](/en/v1.57/user-manual/tools/mcp-connector#mcp-connector).
# Password recovery
Source: https://docs.zylon.ai/en/v1.57/user-manual/password-recovery
Change your password or reset it in case you have forgotten it
## Change password
1. Go to your profile.
![]()
2. Click on **change password** and setup your new password.
![]()
## Reset password
Only administrator can reset a user password. To do so the administrator needs to use Zylon CLI to perform the action.
If you are an administrator, [learn how to do it.](/en/v1.57/operator-manual/configuration/cli#update-password)
# Querying company documents
Source: https://docs.zylon.ai/en/v1.57/user-manual/querying-company-documents
Ask questions over your project’s knowledge base, including connected repositories.
1. Start a new chat in the relevant **project**.
2. (Optional) **Scope** the chat to a **folder** if you know where the answer lives.
3. Ask your question. The assistant retrieves relevant snippets and replies with **citations** you can open to the exact passage.
4. If needed, refine the question or adjust the folder scope.
> You can also paste a **URL** in the prompt to fetch and use the content from that page for the current turn.
# Quick Start Guide
Source: https://docs.zylon.ai/en/v1.57/user-manual/quick-start-guide
Get productive with Zylon Workspace in 15 minutes
Complete these essential tasks to start using Zylon effectively. This guide takes about 15 minutes and covers everything you need to be productive.
## Step 1: Create Your First Project (3 minutes)
Projects organize your AI work by topic or team. Start with a simple personal project.
1. **Click "Create Project"** from your dashboard
2. **Name it descriptively** - e.g., "Personal Research" or "Customer Support"
3. **Keep it private** for now (you can share it later)
![]()
Projects are private by default. Only you can see them unless you explicitly share them with others.
## Step 2: Connect Your Knowledge (5 minutes)
Add documents so Zylon can help you with your actual work. Navigate to the Knowledge Base section of your project.
**Option A: Upload Files**
1. **Drag and drop** 2-3 documents you work with regularly
2. **Wait for processing** (usually 2-5 minutes)
3. **Check the knowledge base** to confirm they're ready
**Option B: Connect to an external source, like SharePoint**
1. **Click "Connect SharePoint"** in your project
2. **Authenticate** with your credentials
3. **Select a specific folder** (not the entire site)
![]()
**Supported file types:**
* PDFs, Word documents, Excel spreadsheets
* PowerPoint presentations, plain text files
* SharePoint folders, Confluence spaces, FTP/Samba
## Step 3: Ask Your First Question (3 minutes)
Now test Zylon with a real question about your documents.
1. **Start a new chat** (choose Personal for now)
2. **Ask a specific question** about the documents you uploaded
3. **Review the response** and click on the citations
4. **Ask a follow-up question** to see how Zylon maintains context
**Good example questions:**
```
"What are the key requirements mentioned in [document name]?"
"What's our policy on [specific topic]?"
```
![]()
## Step 4: Try an AI Document (4 minutes)
AI Documents handle complex tasks automatically in the background.
1. **Go to AI Documents** in your project
2. **Choose "Summarize a File"**
3. **Select one of your uploaded documents**
4. **Add instructions** like "Create an executive summary focusing on key decisions"
5. **Click Start** and let it run in the background
![]()
**Other AI Documents to try:**
* **Answer in Bulk**: Upload a list of questions for automatic answers
* **Generate a Draft**: Create new documents from prompts
* **Read & Extract**: Pull specific information from multiple documents
## What You've Accomplished
✅ **Created and organized** your first project\
✅ **Connected knowledge sources** so Zylon can help with real work\
✅ **Had AI conversations** with citations and context\
✅ **Used automated workflows** for complex document tasks
# Real‑time collaboration
Source: https://docs.zylon.ai/en/v1.57/user-manual/real-time-collaboration
Co‑edit AI Document outputs with teammates.
AI Document outputs (e.g., summaries, drafts) are editable documents. In shared projects, teammates can **edit together in real time**—you’ll see each other’s cursors and even prompts used for inline AI actions.
# Roles and permissions
Source: https://docs.zylon.ai/en/v1.57/user-manual/roles-and-permissions
Access to the knowledge base is controlled by the project roles.
Knowledge base permissions are governed by **project roles**:
* **Viewer** — can start chats and AI Documents that *use* the Knowledge Base; **cannot** modify the Knowledge Base.
* **Editor** — can **add/remove** Knowledge Base content and structure.
* **Admin / Owner** — full control; can also **transfer ownership**.
> There are no separate “per-document roles—the project role determines what you can do with the project's Knowledge Base.
# Search company documents
Source: https://docs.zylon.ai/en/v1.57/user-manual/search-company-documents
Use Search to discover documents imported from company repositories you can access.
When company repositories (e.g., **SharePoint**) and files are connected and imported into project knowledge bases, those files are **indexed**. Search returns them alongside your other workspace items.
* Type keywords or concepts; matching documents appear with their **source**.
* Select a result to open the file context or the chat/flow where it’s referenced.
> You only see items from repositories and projects you have permission to access.
# Search workspace content
Source: https://docs.zylon.ai/en/v1.57/user-manual/search-workspace-content
Find projects, chats, AI Documents, and files you have access to using Search.
Use the **Seach** tool to search **everything you have access to** in the workspace:
* **Projects** by name
* **Chats** (personal and collaborative you can access)
* **AI Documents** (e.g., summaries)
* **Files** (including uploads and connector imports)
**Open search:** Press **Cmd/Ctrl‑K** to bring up Search anywhere, then type to jump directly to results.
> Results respect permissions—you will only see content from projects you can access.
# Authentication for Sensitive Actions
Source: https://docs.zylon.ai/en/v1.57/user-manual/security/authentication-for-sensitive-actions
Understand when Zylon asks you to authenticate again before performing a sensitive action.
Zylon can ask you to authenticate again before performing actions that could have a significant security or operational impact. This additional check helps protect your workspace if an active session is left unattended or accessed by someone else.
![Re-authentication modal for a sensitive action]()
Authentication freshness does not apply to API requests authenticated with tokens. Token-based integrations do not display this modal, so users running automated flows with API tokens do not need to change their existing workflows.
## When re-authentication is required
The check can be applied to sensitive workspace and backoffice actions, including:
* deleting organizations, projects, gateways, artifacts, users, or tokens;
* creating API tokens or gateways;
* changing membership, roles, or account state; and
* other administrative changes that are protected according to their risk level.
The complete list of currently protected actions and their risk levels is available in the [Operator Manual security reference](/en/v1.57/operator-manual/security/authentication-for-sensitive-actions).
## How it works
When your recent authentication is no longer fresh for the action, Zylon displays a **Confirm Access** modal. Depending on the authentication providers enabled for your instance, you can:
1. enter your Zylon password; or
2. authenticate again with Google or Microsoft SSO.
After the authentication is successfully validated, Zylon normally continues with the action automatically. With Google or Microsoft SSO, the provider redirect can interrupt the original request. If the action does not continue automatically after returning to Zylon, repeat the action.
The time for which an authentication remains fresh depends on the action's risk level and is configured by the operator. See [Authentication Freshness configuration](/en/v1.57/operator-manual/configuration/features/authentication-freshness) for details.
# Sharing with colleagues
Source: https://docs.zylon.ai/en/v1.57/user-manual/sharing-with-colleagues
Share a project with everyone in the organization or invite specific teammates to collaborate.
There are two collaboration models:
## 1) Available to everyone in the organization
* Make the project visible to **all current and future members**.
* Assign a default role: **Viewer** or **Editor**.
* **Viewer:** can start chats and AI Documents (e.g., summarize documents) but **cannot change the knowledge base**.
* **Editor:** can modify the project’s knowledge base (add/remove content).
Projects shared org‑wide display the **organization icon**.
## 2) Invite specific people
* Invite by name and choose a role per person: **Viewer**, **Editor**, or **Admin**.
* The **owner** (creator) can **transfer ownership** if needed.
* Shared projects show the **owner’s avatar with a member count**.
> **Private → Collaborative chats:** When starting a chat you can choose **Personal** (private) or **Collaborative** (shared with project members). Private chats can later be **converted to collaborative** (this **cannot be undone**).
# Creating a Skill
Source: https://docs.zylon.ai/en/v1.57/user-manual/skills/creating-a-skill
Add a new Skill to your project by uploading a Skill file.
Project admins and editors can add a new Skill directly inside a project.
## Steps
1. Open your project and go to the **Skills** tab in the sidebar.
2. Click **New Skill**, then choose **Upload from your device**.
3. Drag a Skill file onto the dropzone (a `.zip`, `.skill`, or `SKILL.md` file), or click **Add Files** to browse your device.
4. Check the name and description Zylon picked up from the file.
5. Click **Install**.
![Choosing how to create a new Skill]()
Your new Skill now appears in the project's Skills list and is ready to use in chat.
Only upload Skills from sources you trust — a Skill's instructions run automatically whenever someone uses it.
Need a Skill that everyone in the organization can reuse, not just this project? Ask an admin to publish it from [Managing Organization Skills](/en/v1.57/user-manual/managing-organization-skills), then [install it](/en/v1.57/user-manual/skills/installing-from-organization) into any project that needs it.
# Installing an organization Skill
Source: https://docs.zylon.ai/en/v1.57/user-manual/skills/installing-from-organization
Reuse a Skill your admin already published, without building it yourself.
If your organization admin has published Skills at the organization level, you can add any of them to your project in a couple of clicks — no need to recreate one from scratch.
## Steps
1. Open your project and go to the **Skills** tab in the sidebar.
2. Click **New Skill**, then choose **Install from organization**.
3. Browse the list of Skills published by your admin.
4. Click **Install** next to the one you want.
![Browsing and installing a Skill from the organization library]()
The Skill now shows up in your project's Skills list, right alongside any Skills created directly in the project, and is ready to use in chat.
An installed organization Skill is shared, not copied — if your admin updates or removes it, that change applies everywhere it's installed.
# Introduction to Skills
Source: https://docs.zylon.ai/en/v1.57/user-manual/skills/introduction-to-skills
What a Skill is, and when to use one instead of just asking in chat.
A **Skill** is a ready-made instruction pack for Zylon's assistant. Instead of re-explaining how you want a task done every time — "format it like this," "always include these sections," "follow this checklist" — you (or your admin) write it once as a Skill, and then anyone with access can trigger it in chat with a click.
Think of it as a repeatable recipe: a Skill named `xlsx`, for example, can tell Zylon exactly how to clean up, build, or fix a spreadsheet whenever you're working with one.
***
## Where Skills live
Skills exist at two levels:
* **Organization Skills** — published by an admin from the admin panel, and available to be added to any project. See [Managing Organization Skills](/en/v1.57/user-manual/managing-organization-skills).
* **Project Skills** — created directly inside a single project, or installed there from the organization's library. Visible from the **Skills** tab in your project sidebar.
![A project's Skills page listing the Skills available to it]()
***
## What you can do with Skills
* **[Create a Skill](/en/v1.57/user-manual/skills/creating-a-skill)** in a project by uploading a Skill file.
* **[Install an organization Skill](/en/v1.57/user-manual/skills/installing-from-organization)** into your project without building anything yourself.
* **[Use a Skill in chat](/en/v1.57/user-manual/skills/using-skills-in-chat)** by picking it from the message box, or have it apply automatically to every new chat.
Only project admins and editors can add or remove Skills. Viewers can still use any Skill that's already available in the project.
# Using a Skill in chat
Source: https://docs.zylon.ai/en/v1.57/user-manual/skills/using-skills-in-chat
Apply a Skill to a conversation, or have it turn on automatically.
Once a Skill is available in your project, you can bring it into any conversation from the chat message box.
## Steps
1. Start typing in the message box, then click the **+** button.
2. Select **Skills**.
3. Pick one or more Skills from the list.
![The Skills option inside the chat message box menu]()
![Choosing a Skill from the project's list]()
Selected Skills appear as chips above the message box. Click the **×** on a chip to remove it before sending.
![A Skill selected and ready to use in a chat message]()
***
## Turning a Skill on by default
If a Skill should apply to every new chat in a project — without picking it manually each time — a project admin can turn on **Enable on chat by default** for it from the project's **Skills** page.
You can select more than one Skill in the same message. Zylon uses all of them together to shape its response.
# Attach files in chat
Source: https://docs.zylon.ai/en/v1.57/user-manual/tools/attachments
Drop images and documents straight into a chat message so Zylon can read and use them.
Attach files directly to your chat messages — images, spreadsheets, PDFs, Word documents, presentations, and more — so Zylon can read them and use them as context when responding.
Ask your IT administrator to enable file attachments in your system configuration [with the Operator Manual](/en/v1.57/operator-manual/configuration/features/overview) if you don't see this option.
***
## What you can do with attachments
* Ask questions about a document, spreadsheet, or image you've just attached
* Get a summary, explanation, or analysis of its content
* Use a file as context for problem-solving or decision-making
* Attach more than one file to the same message
* Combine attachments with a text prompt for more specific instructions
***
## How to attach a file
There are two ways to attach a file to a message:
1. Click the **+** button in the chat box, then choose **Add images & files**, and pick one or more files from your device.
2. Or simply **drag and drop** files straight onto the chat box.
![The Add images & files option in the chat message box]()
Once attached, each file shows up as a chip above the message box — add your question or instructions and send.
![A file attached and ready to send with a chat message]()
Your message keeps the attachment alongside it in the conversation, so you can always see what Zylon was looking at.
![A sent chat message showing the attached file]()
***
## Supported file types
* **Images** — JPG, PNG, GIF, WebP, SVG, BMP
* **Documents** — PDF, Word, PowerPoint, Excel, CSV/TSV, plain text, HTML, RTF, ODT, EPUB, Outlook email (`.msg`, `.eml`)
Exactly which file types and how many files you can attach depends on how your admin has configured Zylon for your organization.
***
## Limitations
* The number of files per message and the maximum file size are set by your admin, and may vary by file type.
* If a file is larger than usual, Zylon warns you before continuing — you can still send it, or add it to the project's Knowledge Base instead, which handles large files better.
* Understanding an image depends on its clarity and resolution; very large or complex files may produce less detailed results.
* Your organization's selected AI model has to support the type of file you're attaching (for example, image understanding).
# Database Connector
Source: https://docs.zylon.ai/en/v1.57/user-manual/tools/database-connector
The Database Connector allows you to securely connect a shared database to a **Project**, making its data available to all project members through chat.
> **Important change**: Database connectors are no longer added directly inside a chat. They are now **project-level shared connectors**, managed from the Project sidebar.
Ask your IT administrator to enable the Database Connector in your system configuration [with the Operator Manual](/en/v1.57/operator-manual/configuration/features/overview).
***
## Creating a Database Connector
To create a database connector:
1. Open your **Project Sidebar**
2. Click **Connectors**
3. Click **Create connector**
4. Select **Database**
5. Enter the required **connection details**
6. Establish the connection
Once the connection is successful, additional configuration options become available.
***
### Connection strings made simple
A connection string is like an address that tells the system where to find your database and how to access it. Your IT team can help you build the right connection string for your database.
#### Supported database types
* Microsoft SQL Server
* PostgreSQL
* MySQL
* DB2
#### Connection string
**Security Notes**:
* Never share your connection strings with others
* Use only the databases your IT team has approved
* Make sure the user is read-only
Here's what each part means (ask your IT team for the correct values):
```
SQL Server: mssql+pyodbc://username:password@server:1433/database
PostgreSQL: postgresql://username:password@server:5432/database
MySQL: mysql+mysqldb://username:password@server:3306/database
DB2: db2+ibm_db://username:password@server:50000/database
```
**Examples**
```sql Microsoft SQL Server theme={null}
mssql+pyodbc://sa:password123@server.company.com:1433/SalesDatabase
mssql+pyodbc://dbuser:mypassword@192.168.1.50:1433/CustomerData
mssql+pyodbc://localhost:1433/TestDB?TrustServerCertificate=yes
```
```sql PostgreSQL theme={null}
postgresql://postgres:admin123@database.company.com:5432/company_data
postgresql://user:password@10.0.0.25:5432/sales_db
postgresql://localhost:5432/public_data
```
```sql MySQL theme={null}
mysql+mysqldb://root:password@mysql.company.com:3306/customer_info
mysql+mysqldb://appuser:secret123@127.0.0.1:3306/inventory
mysql+mysqldb://localhost:3306/reports
```
```sql DB2 theme={null}
db2+ibm_db://db2admin:password123@db2server.company.com:50000/SALESDB
db2+ibm_db://dbuser:mypassword@192.168.1.50:50000/PRODDATA
db2+ibm_db://localhost:50000/TESTDB
```
Remember: Replace `username`, `password`, `server`, and `database` with your actual values.
## Advanced Configuration
After the database connection has been established, you can configure advanced parameters to control how the database is used.
### Table and Schema Restrictions
You can limit the connector’s access to:
* Specific **schemas**
* Specific **tables**
This helps:
* Reduce unnecessary data exposure
* Improve query accuracy
* Prevent the LLM from querying irrelevant data
### Connector Description
You can define a **description** for the database connector.
This description is provided to the LLM and should explain:
* What the database contains
* How the data is structured
* Any important rules or conventions
A good description significantly improves the quality of queries generated by the LLM.
***
## Using the Database Connector in Chat
Once created, the database connector can be used in chats:
1. Open or create a chat within the project
2. Use the **Connectors selector** in the chat input
3. Enable the database connector
When enabled, the LLM can query the database as part of the conversation.
***
## Pre-Selected Connectors
Project administrators can configure database connectors to be **pre-selected for every new chat** in the project.
This is especially useful when:
* The database is a core part of the project workflow
* Non-technical users need access to MCPs or databases without having to deal with complex configuration
* Consistent data access is required across all conversations
***
## Personal and Private Usage
If a user wants to configure their **own database connectors** without sharing them:
1. Create a **private project**
2. Create database connectors using the same process
3. Use them exclusively within that private project
Private projects allow experimentation or personal integrations without affecting shared environments.
***
## Requirements and Considerations
* The database must be reachable from the connector environment
* Network access, firewalls, and IP allowlists may need configuration
* Queries generated by the LLM respect the connector’s configured scope
***
## Security
* Credentials are stored securely
* The LLM can only access data allowed by the connector configuration
* Schema and table restrictions are enforced at query time
***
## Database connectivity troubleshooting
If your database connector hangs indefinitely or times out, verify network connectivity from the machine where Zylon is installed.
### Test the connection
Run this command from the machine where Zylon is installed:
```bash theme={null}
curl -v telnet://your-db-host:port
```
### Interpret results
**Successful connection:**
```
* Connected to your-db-host (xxx.xxx.xxx.xxx) port xxxx
```
Network connectivity is working correctly. If issues persist, contact support.
**Connection timeout:**
```
* Failed to connect to your-db-host port xxxx: Operation timed out
```
Network problem detected. Check firewall rules, security groups, and IP allowlists.
**Connection refused:**
```
* Connection refused
```
The database server is not listening on that port. Verify the database is running and configured to accept external connections.
### Common causes
* Firewall blocking outbound traffic from the Zylon host
* Security groups / ACLs blocking the database port
* Incorrect hostname or port
* Database not accepting connections from Zylon's IP
# Extended thinking
Source: https://docs.zylon.ai/en/v1.57/user-manual/tools/extended-thinking
Enable deeper, step‑by‑step reasoning for richer answers.
Turn on **Extended thinking** when you want the model to **reflect before answering**. You’ll see a “thinking” trace as it plans and critiques its own approach.
* Good for open prompts (drafting emails, planning, multi‑criteria decisions).
* Particularly helpful for **math/quant** reasoning.
* Can be combined with other tools like **Numeric analysis**.
> Extended thinking can take longer than a direct answer because it performs deliberate planning first.
# Using tools — overview
Source: https://docs.zylon.ai/en/v1.57/user-manual/tools/introduction-to-tools
Tools extend the chat agent for deeper reasoning and data analysis.
The chat can use tools to improve quality and handle data tasks:
* **Extended thinking** — lets the model think before answering; useful for open‑ended or multi‑step problems.
* **Numeric analysis** — run SQL‑like queries and charting against a **single CSV** from your knowledge base.
* **URL fetch** — paste a web **URL** and the assistant will fetch and use that page’s content for the response.
> You can enable **multiple tools together** (e.g., Extended thinking + Numeric analysis) when appropriate.
# MCP Connector
Source: https://docs.zylon.ai/en/v1.57/user-manual/tools/mcp-connector
The MCP (Model Context Protocol) Connector allows you to integrate external MCP servers into a **Project**,exposing their tools to the LLM in a controlled and shareable way.
> **Important change**: MCP connectors are no longer added directly inside chats. They are now **project-level shared connectors**.
Ask your IT administrator to enable the MCP Connector in your system configuration [with the Operator Manual](/en/v1.57/operator-manual/configuration/features/overview).
***
## Creating an MCP Connector
To create an MCP connector:
1. Open your **Project Sidebar**
2. Click **Connectors**
3. Click **Create connector**
4. Select **MCP**
5. Configure the **MCP connection details**
6. Check **Bearer Auth** and set the token if you MCP requires it
7. Establish the connection
Once the connection is successful, you can configure which MCP tools are available.
***
## Tool Selection
After the MCP connection is established, you must select the tools the connector will expose.
### Why Tool Selection Matters
* Limits what the LLM can invoke
* Reduces noise and unintended behavior
* Improves reliability and safety
You can:
* Enable or disable individual tools
* Update tool selection later without recreating the connector
Only selected tools will be available when the connector is used in a chat.
***
## Using the MCP Connector in Chat
Once created, MCP connectors can be used in chats:
1. Open or create a chat within the project
2. Use the **Connectors selector** in the chat input
3. Enable the MCP connector
The LLM will then be able to invoke the selected MCP tools during the conversation.
***
## Pre-Selected Connectors
Project administrators can configure MCP connectors to be **automatically enabled for every new chat** in the project.
This is recommended when:
* MCP tools are a standard part of the workflow
* Users should not manually manage tool selection
* The project relies on consistent tool availability
***
## Personal and Private MCPs
If a user wants to add or experiment with **personal MCP connectors**:
1. Create a **private project**
2. Create MCP connectors using the same creation flow
3. Use those connectors only within that project
This allows safe experimentation without impacting shared projects.
***
## Requirements and Considerations
* The MCP server must be reachable from the connector environment
* Only MCP-compliant tools are supported
* Tool permissions are enforced based on connector configuration
***
## Security
* Only selected tools are exposed to the LLM
* MCP connectors do not grant unrestricted access
* Tool availability is controlled at the connector level
# Numeric analysis
Source: https://docs.zylon.ai/en/v1.57/user-manual/tools/numeric-analysis
Analyze a CSV from your knowledge base with natural‑language queries.
Use **Numeric analysis** to analyze a **single CSV** stored in your project’s knowledge base.
**How it works**
* You select the CSV file to analyze.
* You activate the **Numeric Analysis** tool.
* Your natural‑language prompt is translated into an **SQL query** and run against the CSV **as if it were a database**.
* Results are rendered as **tables or charts**.
**Tips**
* CSV must be **well‑formed** (single header row; no formulas or multiple sheets).
* Ask for **tables** or specific **charts** (bar, line, heat map, etc.).
* Be as explicit as possible regarding the **column names to be used**. The agent doesn't know your data structure.
* Keep queries grounded in the data present; **external drivers** aren’t inferred unless provided as documents or via a fetched URL in the same chat.
> You can use **Extended thinking + Numeric analysis** together for multi‑step analyses.
# Web search
Source: https://docs.zylon.ai/en/v1.57/user-manual/tools/web-search
Browse the internet to find up-to-date information.
Ask your IT administrator to enable the Web Search tool in your system configuration [with the Operator Manual](/en/v1.57/operator-manual/configuration/features/overview).
Enable **Web search** when you want Zylon to **look things up online** instead of relying only on what it already knows. When this is on, Zylon can **open webpages** and use information from the internet to craft an answer.
This is ideal for anything that changes often (new releases, pricing, regulations, product specs, benchmarks, current events, etc.).
## What you get
* **Up-to-date answers** based on live web content
* **Links and source references** so you can verify where information came from
* Better results for queries that require **fresh context** or **specific details** (dates, version numbers, policy changes)
## When to use it
* “What changed in X recently?”
* “What’s the latest version of Y and what are the breaking changes?”
* “Find official docs for Z and summarize the setup steps.”
* “Compare these products using current specs and pricing.”
## How it appears in chat
When Web search is enabled, you’ll see it available in the chat input (alongside other options like knowledge sources and connectors). Once enabled for the conversation, Zylon can search the web and include helpful sources in its response.
## Notes & best practices
* Prefer **specific prompts** (what you want compared, which region, which timeframe).
* Ask for **sources** when accuracy matters (“include links” / “cite your sources”).
* Web results can vary in quality—Zylon will prioritize reputable sources when possible, but you should still verify critical details.
# Uploading files
Source: https://docs.zylon.ai/en/v1.57/user-manual/uploading-files
Add knowledge to a project by uploading local files or importing from a connector.
Every project has its **own knowledge base**. You can populate it by:
* **Uploading files from your device.** Drag & drop or pick files. Local uploads are **static**—re‑upload if the source changes.
* **Importing via a connector (e.g., SharePoint).** You can select **files or entire folders** you have access to. Ingestion progress is shown.
> **Combine sources:** It’s fine to mix local uploads and connector imports in the same project.
# What is Zylon Workspace?
Source: https://docs.zylon.ai/en/v1.57/user-manual/what-is-zylon-workspace
Learn about Zylon's collaborative AI workspace and how it transforms company knowledge into productivity
Zylon is an enterprise AI platform delivering private generative AI and on-premise AI software for regulated industries, enabling secure deployment inside enterprise infrastructure without external cloud dependencies. Zylon Workspace is the collaborative AI interface where your team works with artificial intelligence daily. It's designed to replace ChatGPT or Claude with a secure, on-premise solution.
![]()
## Core Components
**Projects**
Organize your AI work by topic, team, or use case. Each project has its own knowledge base and custom settings.
**Search**
Find documents using any phrase or keyword you remember, not just titles. Zylon searches the full content of your company's knowledge base and presents matching documents.
**Chat Assistant**
Ask questions and get answers from your company's documents. Includes citations and built-in tools for analysis.
**AI Documents**
Automated workflows that handle complex tasks like document summarization and bulk Q\&A in the background.
## Key Benefits
* **Unlimited usage** - No token limits or per-query costs
* **Complete privacy** - Your data never leaves your infrastructure
* **Custom behavior** - Tailor AI responses for different use cases
* **Team collaboration** - Share projects and work together on AI tasks
## Getting Started
1. **[First Day FAQs](/en/v1.57/user-manual/first-day-faqs)** - Quick answers to common questions
2. **[Quick Start Guide](/en/v1.57/user-manual/quick-start-guide)** - Complete your first tasks in 15 minutes
3. **[Working in Projects](/en/v1.57/user-manual/what-is-zylon-workspace)** - Learn the basics of project organization
Always verify AI responses using the provided citations, especially for business-critical decisions.
# When to use AI Documents
Source: https://docs.zylon.ai/en/v1.57/user-manual/when-to-use-agent-flows
Use AI Documents for comprehensive document work that goes beyond quick chat answers.
Use **AI Documents** instead of chat when you need **comprehensive processing**:
* **Long files / full‑document coverage** (e.g., 300‑page RFPs).
* Batch operations (ask many questions at once).
* Drafting longer documents from multiple sources.
* Structured extraction at scale.
AI Documents **run in the background**, so they aren’t optimized for fast, partial answers—**they process everything that’s required from the knowledge base** to produce complete results.
The result is an editable document that can be exported as a PDF or a Word document for further edition.
# When to use the chat assistant
Source: https://docs.zylon.ai/en/v1.57/user-manual/when-to-use-chat-assistant
Ask direct questions or use it as a thought partner for open-ended tasks.
Use the chat for two patterns:
1. **Direct Q\&A on your knowledge base** — when you know the answer should be in your project’s documents. Answers include **inline citations** to exact source passages.
2. **Open‑ended “thought partner” work** — enable **Extended thinking** for deeper reasoning (e.g., drafting replies, planning meetings, or multi‑step tasks).
> You can **scope** a chat to the **entire Knownledge Base** or a **specific folder** or **file** to help the model focus.
# Workspace Look & Feel
Source: https://docs.zylon.ai/en/v1.57/user-manual/workspace-look-and-feel
Customize Zylon Workspace branding and appearance for your organization
As an administrator, you can customize Zylon Workspace to match your organization's branding and preferences. Zylon is a fully white-label solution.
![]()
## Customization Options
**Company Branding**
* **Workspace Name**: Choose the name of the Workspace (e.g., "Acme GPT")
* **Company Logo**: Upload your organization's logo for the interface
* **AI Assistant Name**: During installation, you can also choose what to call your AI (e.g., "Acme Assistant", "CompanyBot").
Refer to the Operator Manual to learn how to do it.
## Accessing Customization Settings
Only users with Administrator privileges can modify workspace appearance. Contact your IT team if you need these permissions.
1. **Click on the Workspace name** on the top right
2. **Select "Settings"** section
3. **Make your changes** to the Workspace Name and Logo
4. **Save and apply** changes organization-wide
![]()
# Changelog
Source: https://docs.zylon.ai/en/v1.57/changelog/overview
**⚠️ Action required before updating to version 1.57.X**
Follow the complete [1.57 migration guide](/en/v1.57/changelog/guides/1-57-0) before updating.
## 💼 Workspace
### ✨ Features
* **Skills**: Teach your Zylon agent to perform complex tasks with ready-made instruction packs. [Check more](/en/v1.57/user-manual/skills/introduction-to-skills)
* **Organization Skills**: Add and manage Skills at the organization level, enabling centralized skill deployment across workspaces. [Check more](/en/v1.57/user-manual/managing-organization-skills)
* **Google Drive Integration**: Connect your Google Drive directly to Zylon for seamless document access and collaboration. [Check more](/en/v1.57/user-manual/connectors/google-drive)
* **Guardrails UI**: Visual interface to configure and manage AI guardrails for safer, more controlled interactions. [Check more](/en/v1.57/operator-manual/backoffice/guardrails)
* **Session Freshness**: Improved session handling with automatic freshness checks to maintain connection stability.
* **Attach documents in chat**: Drop images and documents straight into a chat message so Zylon can read and use them as context. [Check more](/en/v1.57/user-manual/tools/attachments)
* **Block downloads by org admin configuration**: Admins can now block downloads of uploaded Knowledge Base files and AI-generated resources at the organization level. [Check more](/en/v1.57/user-manual/block-resource-downloads)
## 🛠️ Platform
### ✨ Features
* **Resource Monitor**: New API to monitor system resources and AI workload metrics in real-time.
* **ARM64 Support**: Full support for ARM64 architecture deployments.
* **Improved performance**: Faster inference, better concurrency management, and more performant web search.
## 💼 Workspace
### ✨ Features
* **Full enterprise redesign**: The Workspace has been fully redesigned with a new look and feel tailored for enterprise environments.
* **Knowledge Base redesign**: The Knowledge Base has been fully redesigned to be far more flexible.
* Drop entire folders from your system into the Knowledge Base.
* Navigate inside folders with a macOS-style double-click interaction.
* Upload documents or folders directly into a specific folder.
* Select multiple documents or folders and move them.
* Use a context menu with right click support.
* **Agent Flows renamed to AI Documents**: Agent Flows are now called AI Documents across the product.
* **Improved support for smaller screens**: Although Zylon is not a mobile app, the new redesign significantly improves the experience on smaller screens.
## 🛠️ Backoffice
### ✨ Features
* **Usage dashboard for token consumption**: Backoffice now includes a usage dashboard to track token consumption. This feature requires [audit logging](/en/v1.57/operator-manual/configuration/features/feat-audit) to be enabled.
## 🛠️ Platform
### ✨ Features
* **Audit logs for SIEM and security workflows**: Zylon now provides stronger auditability and security log workflows for SIEM integrations and operational reviews. See [Auditability & AI Governance](/en/v1.57/operator-manual/auditability-ai-safety/), [log delivery and storage](/en/v1.57/operator-manual/backoffice/log-delivery-storage), and the [Backoffice logging API](/en/v1.57/developer-manual/build-with-zylon/backoffice-api/logging).
* **Log retention policy controls**: Added retention policy support for stored logs. See [hard delete configuration](/en/v1.57/operator-manual/configuration/cron-tasks/hard-delete).
* **Active Directory / LDAP support**: Zylon now supports enterprise directory integration through [Active Directory / LDAP](/en/v1.57/operator-manual/authentication/ldap).
* **One-time password for root admin after every CLI login**: Root administrator access through the CLI now requires a one-time password after every login. See [CLI configuration](/en/v1.57/operator-manual/configuration/cli).
* **Vision-based PPTX extraction pipeline**: Added a new pipeline for PPTX files that leverages vision models to improve the accuracy and quality of information extraction. See [vision-based file processing](/en/v1.57/operator-manual/configuration/features/feat-file-vision).
### 🐛 Bug Fixes
* Fixed a bug that could sometimes cause MCPs to fail a chat even when they were not selected.
* **Improved memory management in Web Search**: Improved memory management in the [Web Search tool](/en/v1.57/user-manual/tools/web-search).
* Delivered multiple UI fixes and polish updates as part of the redesign rollout.
**⚠️ Action required before updating to version 1.55.X**
This release changes the default AI model family to Qwen 3.5 and disables automatic model pull by default.
If you install the platform update before downloading the required model, AI services will fail to start.
Follow the complete [1.55 migration guide](/en/v1.57/changelog/guides/1-55-0) before updating.
## 💼 Workspace
### ✨ Features
* **New Model Support + New Default Family**: Added support for Qwen 3.5, experimentally Ministral, GLM 4.7 and NVIDIA Nemotron models. Qwen 3.5 is now the default baseline family, improving reasoning quality, agentic behavior, and response quality.
* **New Workspace Tools in Chat**: With the new model stack, chat can now list content, fetch content, create summaries/analysis, and generate blank documents from chat context.
* **Project Settings Instructions Revamp**: Project settings now uses a single custom instruction input instead of two. This simplifies configuration and improves the UX.
* **Automatic Knowledge Base Synchronization**: Integrations can now sync automatically after configuration. Manual sync workflows are no longer required for standard usage.
* **Personal Workspace Tokens**: All users can now generate their own personal workspace API tokens directly from their account settings, without requiring administrator intervention.
## 🛠️ Backoffice
### ✨ Features
* **Complete Backoffice redesign**: The Backoffice has been fully redesigned with major UI/UX improvements to make platform administration clearer, faster, and more consistent.
## 🛠️ Platform
### ✨ Features
* **Platform metrics for AI/GPU visibility**: You can now collect and consume platform metrics, including GPU and AI workload metrics, to improve observability and operational visibility. See [Observability configuration](/en/v1.57/operator-manual/configuration/observability/overview).
### 🐛 Bug Fixes
* Fixed bugs when the system is running in a machine with IPv6 enabled.
**⚠️ Action required before updating to version ≥ 1.54.0**
This release requires migrating to the new CLI version before updating. Skipping this step will cause a critical failure and Zylon will be unable to start.
This update requires 45–60 minutes of planned downtime. Plan accordingly and notify your users before starting.
This version contains a breaking change regarding Workspace API Tokens.
Follow the complete [1.54.0 migration guide](/en/v1.57/changelog/guides/1-54-0) for full details.
## 💼 Workspace
### ✨ Features
* **Audit Logs Revamp:** Enhanced visibility and filtering capabilities for audit trails with granular tracking of user actions.
* **Confluence On-Prem Connector:** Integration with on-premises Confluence instances for seamless document access and collaboration. [Check more](/en/v1.57/user-manual/connectors/confluence-server)
### 🐛 Bug Fixes
* Fixed crashes when processing excessively large SQL queries with the DB Connector.
* Added proper titles for MCP connectors when only one tool is present.
* Fixed error on chats when the context compression happened.
* Optimized the organization switcher for long lists, improving usability.
## 🛠️ Platform
### ✨ Features
* **Backoffice:** The Platform Backoffice is used by Operators to manage platform-level access and developer environments. [Check more.](/en/v1.57/operator-manual/backoffice/introduction)
* **AI Gateways:** A dedicated, isolated software service that sits at the boundary between clients and Zylon's internal APIs. [Check more.](/en/v1.57/operator-manual/backoffice/platform-backoffice#gateways)
**⚠️ Action required before updating to version ≥ 1.53.0**
This release requires migrating to the new CLI version before updating. Skipping this step will cause a critical failure and Zylon will be unable to start.
This update requires 45–60 minutes of planned downtime. Plan accordingly and notify your users before starting.
Follow the complete [1.53.0 migration guide](/en/v1.57/changelog/guides/1-53-0) for full details.
## 🛠️ Platform
### ✨ Features
* **Full Airgap Installation**: Zylon can now operate in fully air-gapped environments end-to-end — including updates — not just at runtime. For environments with strict network isolation, this unlocks complete lifecycle management without internet access.
* Check the new [airgap installation guide](/en/v1.57/operator-manual/installation/airgap) to get started or to migrate your existing instance.
* **Zylon CLI 2.0.0**: A major overhaul of the command-line interface that simplifies the entire installation process down to a single command — `sudo zylon-cli install `. No more multi-step setup sequences.
* **Setup Wizard**: Configure every aspect of your Zylon instance interactively, without manually editing YAML files. The wizard guides you through all configuration options step by step.
![]()
![]()
## 💼 Workspace
* **DB2 Support**: You can now connect your DB2 databases directly to Zylon, enabling the AI to reason over your enterprise data while maintaining full control and security.
* **MCP integrations enhancements**Bearer token authentication is now supported for MCP integrations, providing more flexible security options. You can also toggle all MCP tools on or off at once, making it faster to configure your workspace.
* **SharePoint Folder Selection**: When using the SharePoint picker, you can now set a default starting folder for the whole org, saving time when navigating to frequently used locations.
* **Extended Analytics Window**: Analytics data is now available for the last 12 months, giving you a longer view of workspace usage and trends.
* **Connector Visibility**: You can now see who created each connector, improving transparency and making it easier to manage integrations across your team.
* **Project Column in Issue Reporting**: The issue tracker now displays a project column with project names, making it easier to organize and filter reported issues.
## 🛠️ Platform
* **Private N8N Deployments**: You can now deploy your own private N8N cluster within your infrastructure. Use it standalone to build custom workflows, or create your own MCP servers for extended AI capabilities. N8N handles your personalized automation while Zylon provides the AI layer, ensuring all data remains secure within your environment.
## 🐛 Bug Fixes
* **Redirection improvements** accross the platform.
* **Connector Creation and Editing Stability**: Fixed multiple cases where connector creation and editing operations were failing unexpectedly.
## 💼 Workspace
### ✨ Features
* **Attach Images in Chat**: You can now attach images directly in chat conversations. This feature requires your model to support image capabilities.
* **Project-Level Connectors**: MCPs and Databases can now be configured at the **project level**, making them reusable across multiple agents and flows while maintaining consistent access control. [Check how to enable Connectors.](/en/v1.57/operator-manual/configuration/features/overview)
* **Web Search Tool in Chat**: Web Search is now available directly inside chat, enabling users to fetch up-to-date information without leaving the conversation. [Check how to enable Web Search.](/en/v1.57/operator-manual/configuration/features/feat-websearch)
* **Edit & Delete Last Interaction**: Quickly fix mistakes or refine prompts by editing or deleting your **last interaction** directly from the chat interface.
### 🐛 Bug Fixes
* **Improved Visibility**: We have enhanced contrast and placement of some UI items for better discoverability and usability.
* **Duplicate AI Document for Running Flows**: You can now duplicate AI Documents even while they are still running, enabling faster iteration and experimentation.
* **Bulk Q\&A Duplication Fix**: Resolved an issue where bulk Q\&A duplication failed under certain conditions.
* **Chat Lock When MCP Tool Selected**: Fixed a bug where selecting a broken tool prevented users from continuing chat interactions while MCP was active.
## Expected downtime
Around 1 hour because there are changes in the Low AI Layer that require large content to be downloaded.
## When to update recommendations
Update out of business hours to avoid impacting users for a long period of time.
## 💼 Workspace
### ✨ Features
* **Message Editing & Deletion**: Made a mistake in the chat? No problem! You can now delete and edit your last messages in private and collaborative chats, giving you more control over your conversation history and reducing friction when refining your inputs.
* **Database Connector Enhancements**: The database connector now supports views and stored procedures, providing quick access to your data without leakage risks. This enables more flexible data integration while maintaining security boundaries.
* **Knowledge Base Performance Improvements**: We've delivered major performance upgrades across the Knowledge Base, especially when loading and searching documents across the application.
### 🐛 Bug Fixes
* **Improved UX when linking from projects**: more space for you to navigate your artifacts
## 💼 Workspace
### ✨ Features
* **CSV Bulk User Upload**: You can now upload multiple users at once via CSV, fully integrated with seat-control and license-tracking. Saving time for admins onboarding large teams and reducing manual errors.
* **Password Management Enhancements**: Users can now update their own passwords, and admins can reset passwords directly from the workspace. Better security hygiene and less administrative overhead.
* **Developer Mode**: We're introducing **Zylon Developer Mode**, enabling users to authenticate and interact with the Zylon API, unlocking deeper integrations and customization of workflows.
This will enable organizations to automate workspace operations from internal scripts and connect Zylon in custom backend services.
* **Token Management**: Developers and Zylon admins can now create, revoke, and manage API tokens directly inside the workspace. This change reduces operational friction when building integrations.
* **Permission Update**: Viewers are now **restricted from downloading files** in the Knowledge Base, ensuring sensitive information remains controlled.
### 🐛 Bug Fixes
* Centered search bar on Issue tracker for better usability.
* Viewers are now forbidden from downloading files.
## 🛠️ Platform
### ✨ Features
* **Expand Zylon with your own tools and workflows without additional infrastructure: Zylon** now supports **Anthropic-compatible API endpoints**, enabling seamless tool integrations.
This unlocks compatibility with:
* **N8N**
* **LangChain tools**
* **Custom Automations** built in-house
* **Enhanced Monitoring and Performance Tracking**: We've improved observability of inference workloads for more precise performance tuning and issue diagnosis
## 🛠️ Platform
### 🐛 Bug Fixes
* Status Page:
* Now it requires login to be accessed.
## 💼 Workspace
### 🐛 Bug Fixes
* Enhanced Omnisearch stability when working with linked files.
## 🛠️ Platform
### ✨ Features
* Zylon now offers proxy support. Learn more about it [here](/en/v1.57/operator-manual/configuration/network/proxy).
* Introduced a Status page that provides information about the overall system health at `https://your-zylon-instance.com/status`
### 🐛 Bug Fixes
* Stability improvement for long chats: Fixed crashes that occurred when reducing the context window size.
* Improved system performance during stress tests.
* Increased the number of allowed database connections.
## 💼 Workspace
### 🐛 Bug Fixes
* Database Connector: now supports all SQL column types.
* Analytics Dashboard: Improved weekly reporting accuracy.
* Issue Dashboard:
* Full chat content is now shown when reporting an issue.
* Added the ability to clear the date filter.
* AI Document:
* Fixed a problem that prevented using Zylon AI as a source for creating draft flow.
* Allowed the use of double quotes in questions for the Bulk Q\&A flow.
## 💼 Workspace
### ✨ Features
* **Database Connector Improvements**: Now supports database views and provides richer contextual data, enabling the model to generate more accurate and grounded responses.
* **Customizable Top Users View**: Adjust the number of top users displayed in the Usage Dashboard to suit your organizational needs.
* **MCP Connector Integration**: You can now use MCP connectors in your Zylon instance.
* This feature is in **Alpha phase** and [needs to be enabled](/en/v1.57/operator-manual/configuration/features/overview).
* Learn how to use it with the [User Manual](/en/v1.57/user-manual/tools/mcp-connector).
* **Image Support in Chats**: You can now chat with your images, *if the image model is enabled*.
### 🐛 Bug Fixes
* Enhanced stability and performance of file pickers across all application modules.
* Refined error handling mechanisms for improved user experience during edge cases.
* Enhanced collaboration features in shared chat environments for smoother teamwork.
## 🛠️ Platform
* Resolved license validation issue in the Command Line Interface (CLI).
A new CLI version is now available, featuring an improved update process that is more robust. The process now validates system readiness before proceeding and includes automatic self-repair capabilities when errors occur.
You must to download the new version running sudo zylon-cli self-update.
## 💼 Workspace
### ✨ Features
* **GPT-OSS Model Now Available**: You can now access our experimental GPT-OSS model in both 24GB and 48GB configurations, giving you more powerful AI capabilities for complex tasks. More information in [experimental presets](/en/v1.57/operator-manual/ai-presets/presets#experimental-presets).
### 🐛 Bug Fixes
* Improved connection stability and reliability.
* Fixed a bug that could cause crashes when setting up new AI Documents.
* Fixed a rare issue that could cause the AI to get stuck while processing requests.
* Fixed a bug where new AI Documents couldn’t be created if a title wasn’t generated automatically.
* The system now chooses the correct language model for each task more consistently.
* Fixed an issue that affected data syncing between systems.
* Fixed an issue that occasionally affected image interpretation in PPTX files.
## 🛠️ Platform
* Use your own AI models: You can now plug in your own fine-tuned AI models without losing any of the platform's features. This gives you more control and flexibility over how the AI behaves. More information in [customizing the default presets](/en/v1.57/operator-manual/ai-presets/advanced-customization).
* Vision support improved: Fixed a bug that sometimes prevented AI tools from loading when visual (image) features were turned on.
## 💼 Workspace
### ✨ Features
* Database Connector: Connect seamlessly to PostgreSQL, MySQL, and MSSQL databases and ask questions in chats, enabling intuitive data retrieval without
writing SQL queries.
* This feature is in **Alpha phase** and [needs to be enabled](/en/v1.57/operator-manual/configuration/features/overview).
* Learn how to use it with the [User Manual](/en/v1.57/user-manual/tools/database-connector).
* AI Document - New menu options for an enhanced user experience:
* Retry: Allows users to restart failed workflows with a single click.
* Duplicate: User is taken a new workflow prefilled with the same data as the original
### 🐛 Bug Fixes
* When adding new members to projects search finds users by email.
* When the knowledge base had only processing files source selector showed 0 files instead of empty state.
* Omnisearch finds folders correctly.
## 🛠️ Platform
* API Refactor: Enhanced ZGPT API with automatic context management and direct tool integration, streamlining development workflows through intelligent request handling
This update involves a 15-30 minutes of downtime.
Follow [this migration guide before updating.](/en/v1.57/changelog/guides/1-43-0)
## 🛠️ Platform
* Zylon becomes multimodal! Now our platform is able to manage several AI models running in parallel within the same instance.
## 💼 Workspace
### ✨ Features
* Enhanced Slides Content Extraction thanks to run a Vision Language Model (VLM) in conjuntion with a Large Language Model (LLM). Please check the new alternative presets to understand [how to configure and enable it](/en/v1.57/operator-manual/ai-presets/presets#alternative-presets). The brand new capabilities added are:
* **Intelligent Content Understanding**: Implemented VLM-powered extraction that can analyze and understand complex visual content including slides, diagrams, charts, and images.
* **Contextual Analysis**: VLM integration enables better comprehension of slide context, relationships between visual elements, and textual content within images.
* Display the last update time for AI Documents.
### 🐛 Bug Fixes
* Support exporting DOCX files with custom elements (e.g. citations, knowledge sources).
* Resolved an issue where PDF exports had formatting problems with nested lists.
* Fixed an issue with partial answer parsing during streaming.
* Addressed an issue where the issue reporting panel displayed an empty date.
* Resolved a display issue in the artifact linking modal on Microsoft Edge.
This update involves a 15-30 minutes of downtime.
Follow [this migration guide before updating.](/en/v1.57/changelog/guides/1-43-0)
## 💼 Workspace
### ✨ Features
* 🔎 **Omnisearch**: Now able to search for content inside AI Documents and Knowledge Base Documents
* Follow the [instructions to enable it](/en/v1.57/changelog/guides/1-43-0#post-update)
* 📝 **Issue reporting**: Users can now report chats to admin organizations when encountering issues with Zylon's responses.
![]()
![]()
![]()
* 🎨 **New Rendering Engine**: Faster & Smoother Chats with Zylon
* Zylon can now understand and render Mermaid diagrams directly in the chat
* Enhanced readability of code blocks for better clarity and visual appeal
* Chat responses now render smoothly without causing formatting jumps during streaming
* 💬 **Enhanced default chat behaviour**: Enforced use of semantic search when files are selected and no other tools are chosen
* 🔐 **Audit logs control**: Added the ability to turn off audit logs — follow the configuration guide to disable
### 🐛 Bug Fixes
* Ensure project is loaded before navigating to the first chat
* Prevent user to access removed chats by url and show warning when trying to access deleted resources (chat, projects)
* Fixed an issue with breadcrumbs in Omnisearch that caused accessibility issues
* Resolved an issue where numeric analysis was incorrectly disabled during document processing
* Fixed navigation to deleted projects by clearing the last visited project if it no longer exists
* Prevented users from navigating to deleted AI Documents via Omnisearch
* Fixed broken code blocks in streaming when the programming language wasn't detected
## 🛠️ Platform
* Ingest: A unified endpoint for ingestion that supports text, files, and URIs, including support for asynchronous ingestion.
* Reorganize the endpoint structure for better clarity by grouping related endpoints under a common base path.
If you are using the low-level API directly, please review carefully our [Developer Manual](https://docs.zylon.ai/api-reference/how-to-use)
### ✨ Features
* 📁 **Folders**: Organize your knowledge base effortlessly using folders for better management of directly uploaded documents
![]()
* 💬 **Async chats**: You can now close Zylon while your chat continues in the background — multitasking made easier!
* 🔎 **Omnisearch**: Instantly search through your content to quickly navigate to your resources: Documents, Chats, AI Documents.
![image.png]()
💡 *Tip: Use* `Cmd + K` *(Mac)* *or* `Ctrl + K` *(Windows/Linux)* *to open Omnisearch even faster!*
* 🔗 **Links**: Files linked in a knowledge base from another project now stay in sync with the original — no duplicates or outdated versions
### 🛠️ Platform
* 🚫 Deprecated endpoints in Low-Level API have been removed
### ✨ Features
* Users can now create folder in knowledge base
* Users can now move folders and files inside knowledge base via Drag and Drop
![]()
### ✨ Features
* New AI Document. Read & Extract.
![]()
![]()
### ✨ Features
* Export AI Document to PDF/DOCX
* Resumability on chat (now the user is able to connect in realtime to a zylon response and the user can refresh or leave the app and comeback without stopping the answer)
### Bugfixes & improvements
* Fixed a bug that prevented to leave project instructions empty
* Connections to database are properly closed to avoid reaching the limit
* Creating a new Claromentis integration was not possible due to an error
It is essential to update the Zylon web app immediately upon receiving the Update notification, by clicking the
Update button. The app will not function correctly until the update is completed. If any user has issues, clean
cache and refresh.
### ✨ Features
* **Tool Selector**: The user has the ability to select Tools between available: Numeric Analysis, and Extended
Thinking (only available with Qwen 3).
* Numerical analysis (currently in beta): Enables standard operations on tabular data in a textual format, including
calculations such as averages, filtering, selection, and data visualization using plots. At present, this
functionality is available only when a CSV file is selected from the knowledge base. For optimal performance, we
recommend adhering to the following guidelines:
* A single header row should be included.
* Dates should be formatted as yyyy-mm-dd.
* Numbers should follow the format XXXXXXX(.XX).
* Empty cells should contain one of the following
values: "nan", "none", "null", "", "undefined", "n/a", "na", "nat".
### Bugfixes & improvements
* Fixed a bug that prevented Qwen from generating plots in certain situations
* Fixed a problem with Assistant name when company context was set
* Better user experience in small devices in Analytics view
This update involves between 15m to 30m of downtime.
### ✨ Features
* New model is available and set as default in all baseline presets. Take a look to [Qwen
3](https://qwenlm.github.io/blog/qwen3/) page to more detailed information.
* For small presets (24, 32 GB), our new default model is `Qwen 3 14B`.
* For bigger presets (48, 96 GB), our new default model is `Qwen 3 32B`.
* Extended Thinking: New thinking capabilities thanks to Qwen 3 models.
### Bugfixes & improvements
* Fixed a problem in title chat generation that it was creating titles without capital letters.
* Show all tree view for confluence documents when picking files to link
* When doing an interaction documents without content are ignored
* On a existing confluence integration, in case of error during authentication now it tries to log in again
* Force streaming mode in low level API
This release changes the current model to the Qwen 3 models. **This is the way we recommend using Zylon to
support new features and functionality.**
In case you want to keep any of the above settings (model, context window, etc), you have to rollback the preset
as detailed in [**AI Presets Configuration**](/en/v1.57/operator-manual/ai-presets/getting-started).
### Bugfixes & improvements
* Improved the user experience when a user removes themself from a project, showing a warning.
* Released to Sandbox: July 8, 2025
* Released to Stable: -
### Bugfixes & improvements
* Optimized how FE cache works
* Added supported for citations in thinking blocks
* Fixed a problem that caused summaries to crash in some scenarios
* Fixed a problem in source selector, that prevented to use Zylon AI even when it was selected
### Tool selector
Now is possible to select what tool to use
### Agentic Zylon AI
Several improvements and fixes to have better stability.
### Bugfixes & improvements
* Trying to ingest documents from Confluence was failing due to a breaking change in Atlassian API
* Remove file from source selector when the original document has been removed
* Improved chat UI
* Show empty state for file system integration
* Citation with PDF files now open the correct page
### Agentic Zylon AI - Alpha tester program
Zylon AI core is now powered by agents using different tools depending on the task to solve.
The first customer-end agent available for alpha testers provides **analytical query** capabilities to extract
valuable information from tabular data sources like CSVs.
Let us know if you want to join the program to start testing it.
### Transfer project ownership
In case you want to stop being the owner of a project, you can now transfer the ownership to a different user.
### Link files from different projects
Now is possible to upload files once and reuse them in different projects without the need of ingesting them again,
hence improving usability and resources management.
**Bugfixes and improvements:**
* Light files get higher priority than heavy files on ingestion queue to expedite the process and avoid queues
blocked by a single heavy file. More info in [Performance Configuration](/en/v1.57/operator-manual/configuration/performance)
* When a non-UTF-8 HTML is ingested, now the content is processed correctly
* Improved CSV delimiter and header auto-detection
* Improved tables ingestion for higher data retrieval accuracy
* In case Claromentis credentials have changed a modal appears to update them
### File System Knowledge Base Integration
Now is possible to add a new integration for the Knowledge Base, in case you have a File System powered by SMB.
Check how to configure this integration in the [File System Knowledge Base documentation](/en/v1.57/operator-manual/knowledge-base/file-system)
**Bugfixes and improvements:**
* Changing content of AI Documents threw an error even though the content was saved properly
* Changing org in different tabs no longer generates flickering
* Navigate to settings without projects
* Code block extension inside the editor has been improved
### Dashboard analytics for admins
As an admin you are now able to review how users are interacting with the system for a given organization. Check
total projects, chats, chat queries and see analytics aggregated by weeks.
### Automatic chat name
Similar to AI Documents, now chats get an automatic name based on the initial message from the user
### Whitelabel
We’ve added full whitelabel support, so you can now customize the AI assistant name to match your company branding.
By default, the assistant’s name is set to **Zylon**. To change it, simply update the `assistantName` field in your
configuration file with your preferred name.
**Naming Guidelines**
* Keep your agent’s name under 20 characters.
* Avoid using mixed casing (e.g., “MyAIAssistant”).
* Do not include unusual symbols, special characters, or excessive punctuation (for example, “\$uper\_Bot!”).
```yaml theme={null}
assistantName: "Zylon"
```
**Bugfixes and improvements:**
* `Qwen 2.5 14B` is the new default model in the `baseline-24g` preset.
This update involves a 30m/1h of downtime.
A driver update is required before updating to this version!
run `sudo zylon-cli install-drivers --force` to update the drivers.
### Integrations owners from Confluence, Claromentis or SharePoint can sync ingested files and folders
\*\* Only files ingested after the update are elegible for synchronization.\*
### Pin your favourite projects for quick access
**Bugfixes and improvements:**
* UI performance
* Improve readability in long columns in tables inside AI Documents
* Added AI preset for 32Gb (Mistral Small 3 2501)
* Supported Blackwell GPUs (RTX 5080, RTX 5090)
* Project organization overview UI has been improved. Now you can easily check for private, shared and pinned
projects.
* Sources in BulkQ\&A AI Documents now point to the document reference instead of showing the filename and page.
* Long chats are now supported, previously when there was a long chat, new messages disappeared after Zylon
response.
* PPT files are now properly ingested.
* Improved documents retrieval.
## Changes required before updating to Zylon 1.27.3
Nvidia CUDA drivers need to be updated to version 12.9. To do that, follow these steps:
1. Update Zylon-CLI:
```bash theme={null}
sudo zylon-cli self-update
```
1. (Optional) Do a [backup using zylon-cli](/en/v1.57/operator-manual/operations/backup) before starting the process.
2. Prepare and update Nvidia Drivers and Toolkit:
```bash theme={null}
sudo zylon-cli setup
```
1. Reboot machine and check that `nvidia-smi` is working well:
```bash theme={null}
sudo reboot
nvidia-smi
```
1. Update Zylon to 1.27.0 using:
```bash theme={null}
sudo zylon-cli update
```
### New organization picker to switch organizations without logging out
### SharePoint connector
**Other features:**
* Observability framework
* Now a tooltip with the complete name is shown when a source name is too long in Knowledge Base.
**Bugfixes and improvements:**
* Reset custom instructions modal to empty state when it was closed without saving
* The flow to add users manually to an organization has been improved to make it easier.
* Usability improvements in several application flows
**Changes required due to the new Observability metrics framework**
In order to provide a better support in case something goes south, in this version we have updated how the
observability framework works by including a new tool based on Grafana, beyond the crash reporting mechanism we had
with Sentry. To make it work, please ensure that your firewall is not blocking connections to any of these websites:
* sentry.io (you should have this already properly configured)
* \*.grafana.net (this is the new one required)
Remember that any data we send is completely anonymous and aggregated, and will help us to diagnose any
malfunctioning in the platform and understand how Zylon is being used to expedite support actions.
For those wanting to know more about what has changed, we have evolved the old config file:
```yaml theme={null}
sentry:
enabled: true
environment: "my-company"
```
to this new and more granular one:
```yaml theme={null}
observability:
crashReporting: true
usageMetrics: true
companyIdentifier: "my-company"
```
In case you want to opt out of this, you can add the following snippet to the configuration file, but remember that
doing so will let us blind against any support action from our side:
```yaml theme={null}
observability:
crashReporting: false
usageMetrics: false
```
### New Features
* Chats can now be copy-pasted and it will respect format
* The file picker allows multi file upload
### Bugfixes
* Improved Claromentis integration to account for symlinked files which crashed the integration. Symlinks are not
ingested.
* Made Claromentis file pulling more resilient. A failed file won’t crash the ingestion process; the file will be
marked as failed and the process will continue.
## **Enhanced AI Editor**
We've completely revamped the text editor in AI Documents, focusing on improved functionality and a better user
experience:
* **Inline AI**: You can now prompt inline within a document to include more information or modify existing text.
Simply start typing `/zylon`.
* **Real time collaboration**: Co-create with your peers in real time!
* **CSV export for tables**: Download the results of Bulk Q\&A or any other table as a CSV file.
* **Improved UX**: Enjoy a more flexible table editing experience and more versatile text editing features.
## **Knowledge Base Search**
We've added a dedicated search bar to the Knowledge Base page of each Project so you can find content faster.
## **EML support**
The platform now supports the popular EML email format. Upload your .eml files and use them in Chats and AI Documents
to summarize long threads, query specific information, and more.
## **CSV Export in Chat**
You can now download tables from Chat conversations as CSV files.
# Zendesk User Manual – Clients
Source: https://docs.zylon.ai/en/v1.57/customer-support-manual/zendesk-client-manual
How to submit, track, and manage support requests through the Zylon Help Center.
This guide explains how Zylon users can **submit, track, and manage support requests** through the Help Center.
Each section includes step-by-step instructions.
***
## 1. Accessing the Help Center
### Step 1: Navigate to the Help Center
Go to the **Zylon Help Center (HC)**:
👉 [https://zylonsupport.zendesk.com/hc/](https://zylonsupport.zendesk.com/hc/)
You’ll find options to:
* **Submit a request**
* **View My Requests**
* Access documentation
![Zendesk Help Center - Submit a request]()
***
## 2. Submitting a Request
### Step 1: Open the Request Form
1. On the top navigation bar, click **Submit a request**.
### Step 2: Fill in the Request Details
The request form includes several required fields:
#### 1. Subject
* Write a short, clear summary of your issue or request.
*Example: “Unable to install Zylon app v1.45 on macOS”*
#### 2. Description
* Describe your issue or request in detail.
* Include relevant context, steps to reproduce (for bugs), or screenshots.
#### 3. Type of Issue
Select the most appropriate category:
* **Outage / System Down**
Zylon is completely unavailable or inaccessible for all users.
* **Major Bug**
A critical defect preventing core workflows or key functionality.
* **Minor Bug**
A non-critical issue causing inconvenience but not blocking workflows.
* **Feature Request / Improvement**
Suggestions for new functionality or enhancements.
* **App Installation / Update Issue**
Problems during installation or updates.
#### 4. Zylon Version
* Choose the product version related to your issue (e.g. **v1.45**).
* You can find this in the bottom-right corner of the Zylon app.
***
### Step 3: Submit Your Request
Once all fields are complete:
* Click **Submit** at the bottom of the form.
* A confirmation message will appear, and your request will be created.
***
## 3. Tracking Your Requests
### Step 1: View Submitted Requests
1. From the Help Center, click **My Requests** in the navigation bar.
2. You’ll see a list of all your requests, including:
* **Subject**
* **ID**
* **Created date**
* **Last activity**
* **Status** (Open, Solved, Closed)
![Zendesk My Requests list]()
***
### Step 2: Check Request Details
1. Click any request (e.g. “Download button is not working”).
2. The request detail page shows:
* **Requester**
* **Created / Last activity date**
* **Request ID**
* **Status**
* **Priority**
* **Type of Issue**
* **Zylon Version**
* **Zylon Doctor Output**(optional)
![Zendesk request details view.]()
***
### Step 3: Add to the Conversation
To reply or provide updates:
1. Scroll to the **Add to conversation** section.
2. Type your message or upload files if needed.
3. Click **Submit** or **Send**.
![Add to conversation section in Zendesk]()
***
## Quick Summary
| Action | Where to Go | What to Do |
| - | - | - |
| Submit a new request | **Submit a request** | Fill subject, description, issue type, Zylon version |
| Check request status | **My Requests** | View all submitted tickets |
| Respond or update | **Request Detail** | Add to conversation |
***
## Tips
* Always include your **Zylon version** when reporting issues.
* Try to attach the Zylon Doctor output if your problem is related with your platform status.
* Attach screenshots or logs to speed up troubleshooting.
* You’ll receive **email notifications** when there’s an update to your request.
# Advanced Customization
Source: https://docs.zylon.ai/en/v1.57/operator-manual/ai-presets/advanced-customization
Customize AI models for specialized workloads including fine-tuned models and multi-model configurations
Custom configurations can cause system malfunction. Perform thorough testing before deployment.
## When to Use Custom Configurations
Consider advanced customization when:
* You have **fine-tuned models** optimized for specific domains or tasks
* You need **different sampling parameters** than the preset defaults
* You want to run **multiple specialized models** simultaneously (e.g., one for vision, one for text, one for reasoning)
* You require models from **alternative model families** not included in standard presets
Before proceeding, ensure you:
* Understand GPU memory management principles
* Have access to compatible HuggingFace model repositories
* Know your hardware limitations
* Have a testing environment for validation
## Supported Model Families
Zylon supports these model families for custom configurations:
| Model Family | Example Repository | Use Cases |
| - | - | - |
| **Qwen 3** | `Qwen/Qwen3-14B` | General purpose (default) |
| **Mistral Small** | `mistralai/Mistral-Small-24B-Instruct-2501` | High-quality text generation |
| **Gemma 3** | `google/gemma-3-12b-it` | Efficient inference |
| **Gemma 3n** | `google/gemma-3n-E4B-it` | Optimized small models |
| **GPT-OSS** | `openai/gpt-oss-20b` | Alternative architecture |
Only models from these families are officially supported. Using unsupported families may result in system instability.
## Understanding Configuration Structure
All custom configurations follow this pattern:
```yaml theme={null}
ai:
preset: "" # Start with a base preset
numGPUs: # Optional: for multi-GPU setups
config:
models:
- id: llm # Mandatory: primary language model
# ... configuration
- id: embed # Mandatory: embeddings model
# ... configuration
- id: # Optional: additional models
# ... configuration
```
**Key principles:**
* Every configuration must include `llm` and `embed` models
* Each model needs a unique `id`
* GPU memory must be managed manually when adding/deleting models
***
## Use Case 1: Customizing Existing Models
**Goal**: Modify the preset's default models without adding new ones. This is useful for using fine-tuned versions of existing models or adjusting inference parameters.
### When to Use This Approach
* Swapping the default model for a **fine-tuned version** (e.g., `Qwen3-14B-Medical` instead of `Qwen3-14B`)
* Changing **sampling parameters** (temperature, max tokens, etc.) for different behavior
* Using a **different embeddings model** for improved semantic search
* Adjusting **context window** size based on your use case
### How It Works
Since you're not adding models, you don't need to worry about memory reallocation. Simply specify the model changes in the `config` section, and the preset handles memory allocation automatically.
### Configuration Schema
```yaml theme={null}
ai:
preset: ""
config:
models:
- id: llm | embed # Which model to customize
modelRepo: string # HuggingFace model path
tokenizer: string # Optional: tokenizer path (LLMs only)
promptStyle: string # Optional: qwen, mistral, gemma, gpt-oss
contextWindow: integer # Optional: max context length
samplingParams: # Optional: inference parameters
temperature: float (0.0-2.0)
maxTokens: integer (1-8192)
topP: float (0.0-1.0)
# ... other sampling parameters
```
### Examples
#### Example 1: Using a Fine-Tuned Model
Replace the default model with your domain-specific fine-tuned version:
```yaml theme={null}
ai:
preset: "baseline-24g"
config:
models:
- id: llm
modelRepo: "your-org/qwen3-14b-medical-finetuned"
tokenizer: "Qwen/Qwen3-14B-Instruct" # Use original tokenizer
```
#### Example 2: Adjusting Sampling Parameters
Modify inference behavior without changing the model:
```yaml theme={null}
ai:
preset: "baseline-48g"
config:
models:
- id: llm
samplingParams:
temperature: 0.3 # More deterministic
maxTokens: 2048 # Shorter responses
topP: 0.85 # Focused sampling
repetitionPenalty: 1.3 # Reduce repetition
```
#### Example 3: Using Alternative Model Family
Switch to a different model family while keeping the same memory footprint:
```yaml theme={null}
ai:
preset: "experimental.gpt-oss-24g"
config:
models:
- id: llm
modelRepo: "your-org/gpt-oss-20b-finetuned"
tokenizer: "openai/gpt-oss-20b"
promptStyle: gpt-oss
```
#### Example 4: Custom Embeddings Model
Use specialized embeddings for domain-specific semantic search:
```yaml theme={null}
ai:
preset: "baseline-48g"
config:
models:
- id: embed
modelRepo: "your-org/legal-embeddings-v1"
vectorDim: 1024
```
***
## Use Case 2: Adding New Models
**Goal**: Run multiple specialized models simultaneously. This is more complex because you must manually manage GPU memory allocation across all models.
### When to Use This Approach
* Running a **vision model** alongside your primary text model
* Using **different models for different tasks** (e.g., reasoning model + fast response model)
* Creating **specialized pipelines** that require multiple model types
* Building **multi-modal systems** that process text, images, audio, and other data types
### Understanding GPU Memory Management
The critical concept: **GPU memory is a fixed resource that must be manually divided among all models.**
Each model uses a fraction of total GPU memory, controlled by `gpuMemoryUtilization` (a value between 0.0 and 1.0). The sum of all models' memory allocations cannot exceed **0.95** (reserving 5% for system overhead).
**Default allocation for baseline-24g:**
```
llm: 0.85 (85% of 24GB = ~20.4GB)
embed: 0.10 (10% of 24GB = ~2.4GB)
─────────────
Total: 0.95 (with 0.05 reserved for system)
```
**To add a new model**, you must:
1. Reduce existing models' allocations to free memory
2. Assign the freed memory to the new model
3. Adjust context windows if memory is significantly reduced
### Understanding KV Cache
To understand why memory allocation affects context windows, you need to know about **KV Cache**.
**What is KV Cache?**
During inference, language models store intermediate computations (Keys and Values) for each token they process. This is called the **KV Cache**, and it's what allows models to maintain context across a conversation or document without recomputing everything from scratch.
The KV Cache grows with:
* **Context length**: More tokens in context = more cache storage needed
* **Model size**: Larger models require more cache per token
* **Batch size**: Processing multiple requests simultaneously multiplies cache requirements
**Memory allocation breakdown:**
When you allocate GPU memory to a model, that memory is divided between:
1. **Model weights**: The model parameters (fixed size, \~2 bytes per parameter for FP16)
2. **KV Cache**: Storage for context tokens (grows with context length)
3. **Activation memory**: Temporary computation space during inference
**Example for a 14B parameter model:**
```
Full allocation (0.85 on 24GB = 20.4GB):
├─ Model weights: ~14GB (quantized; original FP32 size would be ~28GB)
├─ KV Cache: ~5GB (supports 16k context)
└─ Activations: ~1.4GB
Reduced allocation (0.50 on 24GB = 12GB):
├─ Model weights: ~14GB (same, but tighter)
├─ KV Cache: ~2GB (now only supports 8k context)
└─ Activations: minimal headroom
```
**Why this matters:**
If you reduce total memory allocation from 0.85 to 0.50, the model weights still need the same space, but you have significantly less room for KV Cache. This means you must reduce the `contextWindow` parameter proportionally to avoid out-of-memory errors during inference.
**Default baseline KV Cache allocations:**
| Preset | Memory Allocation | Context Window | Approx KV Cache |
| - | - | - | - |
| baseline-24g/48g | 0.85 | 16384 (16k) | \~4-6GB |
| baseline-96g | 0.85 | 32768 (32k) | \~8-12GB |
Setting `contextWindow` too high for the allocated memory will cause out-of-memory errors during inference, especially during long conversations or when processing large documents. The errors typically appear as "CUDA out of memory" in the Triton logs.
### Step-by-Step Process
#### Step 1: Know Your GPU Memory
First, identify your total available GPU memory:
```bash theme={null}
nvidia-smi
```
Common configurations:
* **24GB**: RTX 4090, L4
* **48GB**: RTX A6000, L40, L40s
* **80-96GB**: A100, H100
Reserve **5% for system overhead**, leaving **95% for models**:
* 24GB → 22.8GB usable
* 48GB → 45.6GB usable
* 96GB → 91.2GB usable
#### Step 2: Calculate Model Memory Requirements
Model memory depends on **parameter count** and **quantization**. Use this table to estimate:
| Model Size | FP16 (full precision) | FP8 | FP4/AWQ | Typical Use |
| - | - | - | - | - |
| 3-4B | 6-8 GB | 3-4 GB | 2-3 GB | Fast inference, reasoning |
| 7B | 14-16 GB | 7-8 GB | 4-5 GB | Vision models, specialized tasks |
| 14B | 28-32 GB | 14-16 GB | 8-10 GB | Common usage |
| 20B | 40-44 GB | 20-22 GB | 12-14 GB | High-quality generation |
| 32B | 64-68 GB | 32-34 GB | 18-20 GB | Advanced reasoning |
| 70B | 140-150 GB | 70-75 GB | 40-45 GB | Complex tasks |
**Quantization notes:**
* **FP16**: Full precision, best quality, highest memory
* **FP8**: 50% memory reduction, minimal quality loss
* **FP4/AWQ**: 70-75% memory reduction, slight quality degradation
* Most HuggingFace models default to FP16 unless specified (e.g., `-AWQ`, `-GPTQ` suffix)
**Example calculations for 24GB GPU (22.8GB usable):**
```
Scenario 1: Primary + Vision
- Qwen3-14B (FP16): 28GB → Too large alone
- Qwen3-14B (FP4): 10GB → Fits
- Qwen2.5-VL-7B (AWQ): 5GB → Fits
- Embeddings: 2-3GB → Fits
- Total: 17-18GB → ✓ Fits in 22.8GB
Scenario 2: Multiple smaller models
- Gemma-3n-4B: 3GB → Fits
- Qwen2.5-VL-7B (AWQ): 5GB → Fits
- GPT-OSS-20B (FP4): 12GB → Fits
- Embeddings: 2GB → Fits
- Total: 22GB → ✓ Fits in 22.8GB
```
#### Step 3: Convert GB to Memory Utilization Percentages
Once you know the GB requirements, convert to `gpuMemoryUtilization`:
**Formula**: `gpuMemoryUtilization = (Model GB / Total GPU GB)`
**Example for 24GB GPU:**
| Model | Memory (GB) | Calculation | gpuMemoryUtilization |
| - | - | - | - |
| Qwen3-14B (FP4) | 10 GB | 10 / 24 = 0.417 | 0.42 |
| Qwen2.5-VL-7B | 5 GB | 5 / 24 = 0.208 | 0.21 |
| GPT-OSS-20B (FP4) | 12 GB | 12 / 24 = 0.500 | 0.50 |
| Embeddings | 2.5 GB | 2.5 / 24 = 0.104 | 0.10 |
| **Total** | **29.5 GB** | **29.5 / 24** | **1.23** (over 1.00 ✗) |
**Example for 48GB GPU:**
| Model | Memory (GB) | Calculation | gpuMemoryUtilization |
| - | - | - | - |
| Qwen3-14B (FP16) | 30 GB | 30 / 48 = 0.625 | 0.63 |
| Qwen2.5-VL-7B | 5 GB | 5 / 48 = 0.104 | 0.10 |
| Gemma-3n-4B | 3 GB | 3 / 48 = 0.063 | 0.07 |
| Embeddings | 5 GB | 5 / 48 = 0.104 | 0.10 |
| **Total** | **43 GB** | **43 / 48** | **0.90** (under 1.00 ✓) |
Always round down slightly to leave headroom. If calculation gives 0.417, use 0.40 or 0.42.
#### Step 4: Adjust Context Windows Based on Memory
When you reduce a model's memory allocation, you must also reduce its `contextWindow` because there's less space available for [KV Cache](#understanding-kv-cache).
**Rule of thumb**: Context window scales roughly linearly with memory footprint.
**Examples:**
```
Scenario 1: 24GB GPU with vision model
- Primary LLM: 0.85 → 0.50
Context: 16384 → 8192
- Vision: 0.25
Context: 2048
Scenario 2: 48GB GPU with multiple models
- Primary LLM: 0.85 → 0.60
Context: 16384 → 12288
- Reasoning: 0.15
Context: 4096
- Vision: 0.10
Context: 2048
```
#### Step 5: Write Complete Configuration
Now combine all models with their calculated allocations:
```yaml theme={null}
ai:
preset: "baseline-24g"
config:
models:
- id: llm
gpuMemoryUtilization: 0.42 # 10GB for Qwen3-14B FP4
contextWindow: 4096 # Reduced from 8192
- id: llmvision
gpuMemoryUtilization: 0.21 # 5GB for vision model
contextWindow: 1024 # Small for vision tasks
- id: llmfast
gpuMemoryUtilization: 0.12 # 3GB for fast model
contextWindow: 2048
- id: embed
gpuMemoryUtilization: 0.10 # 2.5GB for embeddings
```
**Quantized models in HuggingFace**:
Look for suffixes like `-AWQ` or `-GPTQ` in the model name. If there's no suffix, assume FP16.
Examples:
* `Qwen/Qwen3-14B-Instruct` → FP16 (28-32GB)
* `Qwen/Qwen3-14B-Instruct-AWQ` → FP4 (8-10GB)
* `mistralai/Mistral-Small-24B-Instruct-2501` → FP16 (44-48GB)
### Configuration Schema
```yaml theme={null}
ai:
preset: ""
numGPUs: integer # Optional: for multi-GPU
config:
models:
- id: string # Required: unique identifier
name: string # Optional: display name
type: llm | embedding # Required: model type
modelRepo: string # Required: HuggingFace path
tokenizer: string # Optional: tokenizer path (LLMs)
promptStyle: string # Optional: qwen, mistral, gemma, gpt-oss
contextWindow: integer # Optional: max context length
gpuMemoryUtilization: float # Required when adding models (0.0-1.0)
supportReasoning: boolean # Optional: enable reasoning (LLMs)
multimodal: # Optional: multimodal support (LLMs)
images:
enabled: boolean
maxNumber: integer
samplingParams: # Optional: inference parameters
temperature: float (0.0-2.0)
maxTokens: integer (1-8192)
minP: float (0.0-1.0)
topP: float (0.0-1.0)
topK: integer (1-100)
repetitionPenalty: float (1.0-2.0)
presencePenalty: float (-2.0-2.0)
frequencyPenalty: float (-2.0-2.0)
```
**Critical Rules:**
* Sum of all `gpuMemoryUtilization` must not exceed 1.00
* Each `id` must be unique
* `llm` and `embed` are mandatory and cannot be removed
* Reducing memory allocation requires reducing `contextWindow` proportionally
### Complete Example: Multi-Model Setup
This example demonstrates adding vision and reasoning models to handle different workload types:
**Scenario**: You want three models:
1. **Primary LLM** for general text tasks
2. **Vision LLM** for image understanding
3. **Fast Audio Model** for transcription tasks
**Memory allocation strategy**:
```
Primary LLM: 0.50 (reduced from 0.85)
Vision model: 0.25 (new)
Audio model: 0.10 (new)
Embeddings: 0.10 (unchanged)
───────────────────────────────
Total: 0.95
```
**Complete configuration**:
```yaml theme={null}
ai:
preset: "baseline-24g"
numGPUs: 1
config:
models:
# Primary LLM - Handles general text generation
- id: llm
name: qwen-3-14b-awq
type: llm
contextWindow: 9600 # Reduced from 16384 (~41%) to match memory allocation
promptStyle: qwen
gpuMemoryUtilization: 0.50 # Reduced from default 0.85
supportReasoning: true
samplingParams:
temperature: 0.7
maxTokens: 4096
topP: 0.9
# Embeddings - Mandatory for document processing (unchanged)
- id: embed
gpuMemoryUtilization: 0.10
# Vision LLM - Handles image understanding tasks
- id: llmvision
name: qwen-2-5-vl-7b-awq
type: llm
contextWindow: 1024 # Smaller for image tasks
promptStyle: qwen
gpuMemoryUtilization: 0.25 # New allocation
multimodal:
images:
enabled: true
maxNumber: 1
supportReasoning: false
samplingParams:
temperature: 0.1 # More deterministic for vision
maxTokens: 2048
topP: 0.85
# Fast audio model - Handles transcription tasks
- id: llmaudio
name: gemma-3n-e4b
type: llm
contextWindow: 2048
modelRepo: "/gemma-3n-4b-it-audio" # Fine-tuned for audio
promptStyle: gemma
gpuMemoryUtilization: 0.10 # New allocation
supportReasoning: true
samplingParams:
temperature: 0.5
maxTokens: 1024
topP: 0.9
# Memory verification: 0.50 + 0.25 + 0.10 + 0.10 = 0.95 ✓
```
### Best Practices for Multi-Model Setups
1. **Start minimal**: Begin with smallest viable allocations, increase based on actual usage
2. **Monitor continuously**: Use `nvidia-smi` to track real memory consumption
3. **Test individually**: Validate each model works before combining. Best to isolate issues instead of debugging multiple models at once
4. **Plan for headroom**: Don't allocate the full memory. Leave some buffer for memory spikes
5. **Stress test**: Simulate peak workloads to ensure stability under load
***
## Configuration Parameter Reference
Complete reference for all available parameters.
### Core Parameters (All Models)
| Parameter | Type | Required | Description |
| - | - | - | - |
| `id` | string | Yes | Unique model identifier |
| `type` | string | Yes | Model type: `llm` or `embedding` |
| `modelRepo` | string | Yes | HuggingFace model path |
| `name` | string | No | Custom display name |
| `gpuMemoryUtilization` | float | No | GPU memory fraction (0.0-1.0) |
### LLM-Specific Parameters
| Parameter | Type | Description |
| - | - | - |
| `contextWindow` | integer | Maximum context length |
| `tokenizer` | string | HuggingFace tokenizer path |
| `promptStyle` | string | Format: `qwen`, `mistral`, `gemma`, `gpt-oss` |
| `supportReasoning` | boolean | Enable reasoning capabilities |
| `supportImage` | integer | Number of supported images |
| `supportAudio` | integer | Number of supported audio inputs |
| `samplingParams` | object | Default sampling configuration |
| `reasoningSamplingParams` | object | Sampling for reasoning mode |
### Embedding-Specific Parameters
| Parameter | Type | Description |
| - | - | - |
| `vectorDim` | integer | Output vector dimensions |
### Sampling Parameters
| Parameter | Type | Range | Description |
| - | - | - | - |
| `temperature` | float | 0.0-2.0 | Randomness in generation |
| `maxTokens` | int | 1-8192 | Maximum response tokens |
| `minP` | float | 0.0-1.0 | Minimum probability threshold |
| `topP` | float | 0.0-1.0 | Nucleus sampling threshold |
| `topK` | int | 1-100 | Top-K sampling limit |
| `repetitionPenalty` | float | 1.0-2.0 | Penalty for repeated tokens |
| `presencePenalty` | float | -2.0-2.0 | Penalty for token presence |
| `frequencyPenalty` | float | -2.0-2.0 | Penalty for token frequency |
### Multimodal Parameters (LLMs)
```yaml theme={null}
multimodal:
images:
enabled: boolean # Enable image input
maxNumber: integer # Max images per request
audio:
enabled: boolean # Enable audio input
maxNumber: integer # Max audio files per request
```
***
## Validation Checklist
Before deploying custom configurations:
* [ ] All `id` values are unique
* [ ] `llm` and `embed` models are present
* [ ] Sum of `gpuMemoryUtilization` ≤ 0.95
* [ ] `promptStyle` matches model family
* [ ] `contextWindow` appropriate for memory allocation
* [ ] `tokenizer` matches or is compatible with model
* [ ] Configuration tested in staging environment
* [ ] Monitoring in place for memory usage
## Common Pitfalls
1. **Exceeding 1.0 memory allocation**: Always verify your math
2. **Not reducing context windows**: Large contexts need more memory, adjust accordingly
3. **Mismatched tokenizers**: Use compatible tokenizers for each model
4. **Wrong prompt style**: Each model family requires specific formatting
5. **No testing**: Always validate in non-production first
# Configuration Options
Source: https://docs.zylon.ai/en/v1.57/operator-manual/ai-presets/configuration
Configure enhanced capabilities, multi-GPU setups, and shared memory for optimal performance
## Enhanced Capabilities
Zylon supports additional capabilities that can be combined with any base or alternative preset. These capabilities extend the functionality but are **not enabled by default**.
### Available Capabilities
| Capability | Description | Example Use Cases | Models |
| - | - | - | - |
| `multilingual` | Enhanced support for languages beyond English | International documents, non-English content processing | intfloat/multilingual-e5-large |
### Adding Capabilities
Capabilities are added to presets using a comma-separated format: `,,`
**Examples:**
```yaml theme={null}
# Base preset with multilingual capability
ai:
preset: "baseline-48g,capabilities.multilingual"
# Alternative preset with multilingual capability
ai:
preset: "alternatives.baseline-48g-context,capabilities.multilingual"
# Multiple capabilities (if more become available)
ai:
preset: "baseline-48g,capabilities.multilingual,capabilities.feature2"
```
Capabilities can be stacked with any preset type including base, alternative, and experimental presets.
## Multi-GPU Configuration
If your system has multiple GPUs, you can combine their memory capacity to use higher-tier presets. Select the preset based on **total combined VRAM** across all GPUs.
### Configuration Steps
1. **Calculate total VRAM**: Add up the memory of all GPUs
2. **Select appropriate preset**: Choose preset for the total memory
3. **Configure GPU count**: Set the `numGPUs` parameter
**Configuration Example:**
```yaml theme={null}
ai:
preset: "baseline-48g"
numGPUs: 2 # Using 2 GPUs with 24GB each (48GB total)
```
### Multi-GPU Configuration Examples
| Hardware Setup | Individual GPU Memory | Total VRAM | Recommended Preset | Configuration |
| - | - | - | - | - |
| 2x RTX 4090 | 24GB each | 48GB | `baseline-48g` | `numGPUs: 2` |
| 2x L4 | 24GB each | 48GB | `baseline-48g` | `numGPUs: 2` |
| 4x RTX 4090 | 24GB each | 96GB | `baseline-96g` | `numGPUs: 4` |
| 2x RTX A6000 | 48GB each | 96GB | `baseline-96g` | `numGPUs: 2` |
### Multi-GPU Best Practices
* Ensure all GPUs are the same model for optimal performance
* Verify adequate PCIe bandwidth between GPUs
* Monitor GPU utilization to ensure balanced load
* Consider NVLink connections for better inter-GPU communication when available
**Complete Multi-GPU Example:**
```yaml theme={null}
ai:
preset: "baseline-96g,capabilities.multilingual"
numGPUs: 4 # 4x RTX 4090 (24GB each = 96GB total)
```
## Shared Memory Configuration
The Triton Inference Server uses shared memory to enable zero-copy data transfer between Zylon services and the inference engine. This eliminates serialization overhead and significantly improves inference throughput and reduces latency for high-volume workloads.
### Default Allocation
By default, the inference server allocates **2GB of RAM** for shared memory. This is sufficient for most text-based inference workloads.
### When to Increase Shared Memory
You may encounter `Shared memory allocation failed` errors in these scenarios:
* **Large request queues**: Processing high volumes of concurrent requests where queued input exceeds available shared memory
* **Image-based models**: Vision workloads requiring multiple megabytes per image where batches of high-resolution images quickly exhaust the default allocation
* **Large document processing**: Handling very large documents or multiple documents simultaneously
### Configuration
To increase the shared memory limit, update your Zylon configuration file:
```yaml theme={null}
triton:
sharedMemory:
limit: "4Gi" # Increase from default 2Gi
```
### Recommended Shared Memory by Use Case
| Use Case | Recommended Limit | Reason |
| - | - | - |
| Text-only inference | 2Gi (default) | Sufficient for most text workloads |
| Low-volume vision tasks | 4Gi | Handles occasional image processing |
| High-volume vision tasks | 8Gi | Supports batch image processing |
| Mixed heavy workloads | 8-16Gi | Accommodates concurrent text and vision |
**Important considerations when increasing shared memory:**
* Allocating excessive shared memory can cause pods to be OOMKilled
* Be conservative with increases—start with small increments (e.g., 2Gi → 4Gi)
* Monitor actual usage with Kubernetes metrics before further increases
* Shared memory is reserved from system RAM, reducing available memory for other processes
# Getting Started
Source: https://docs.zylon.ai/en/v1.57/operator-manual/ai-presets/getting-started
Learn the fundamentals of AI presets and how to configure them for your hardware
## Overview
The Zylon AI inferencing engine is the core component that runs artificial intelligence models on your hardware. To ensure optimal performance and prevent startup failures, you must configure the system with the correct preset based on your available GPU (Graphics Processing Unit) memory.
### What are AI Presets?
AI presets are pre-configured settings that optimize the AI models and memory allocation for your specific hardware setup. Each preset is carefully tuned to:
* Load the appropriate AI model size for your GPU/RAM memory
* Allocate memory efficiently to prevent crashes
* Balance performance with available resources
* Enable specific capabilities when needed
Selecting an incorrect preset will prevent the inference engine from starting. The system does not automatically detect your GPU capacity, so manual configuration is required.
## Understanding GPU Memory Requirements
Your GPU (Graphics Processing Unit) has a specific amount of VRAM (Video Random Access Memory) that determines which AI models can run effectively. AI models require substantial memory to operate, and larger models with better capabilities need more VRAM.
### How to Check Your GPU Memory
You can verify your GPU memory using:
* **Command line**: Run `nvidia-smi` command
* **Hardware documentation**: Refer to your GPU manufacturer specifications
The output of `nvidia-smi` will show your GPU model and total memory capacity.
## Quick Start Guide
### Step 1: Identify Your GPU Memory
Run the following command to check your available GPU memory:
```bash theme={null}
nvidia-smi
```
Look for the "Memory" column to find your total VRAM.
### Step 2: Select the Appropriate Preset
Based on your GPU memory, choose the matching preset:
| GPU Memory | Preset to Use | Example Hardware |
| - | - | - |
| 32GB | `baseline-32g` | RTX 5090 |
| 48GB | `baseline-48g` | RTX A6000, A40, L40 |
| 96GB | `baseline-96g` | A100 80GB, H100 |
Always select a preset that matches or is lower than your available VRAM.
### Step 3: Configure Your System
Edit your Zylon configuration file at `/etc/config/zylon-config.yaml`:
```yaml theme={null}
ai:
preset: "baseline-48g" # Replace with your selected preset
```
### Step 4: Apply Configuration
After modifying the configuration file, restart the Zylon services to apply changes:
```bash theme={null}
# Rollout restart of Triton
kubectl rollout restart deploy/zylon-triton
```
### Step 5: Verify Installation
Check that the inference engine started successfully:
```bash theme={null}
# Check logs for successful model loading
kubectl logs deploy/zylon-triton -n zylon --tail=100
```
Look for log messages indicating successful model initialization.
## What's Next?
* Explore [available presets](/en/v1.57/operator-manual/ai-presets/presets) to find specialized configurations
* Learn about [configuration options](/en/v1.57/operator-manual/ai-presets/configuration) for multi-GPU and capabilities
* Dive into [advanced customization](/en/v1.57/operator-manual/ai-presets/advanced-customization) for custom models
* Troubleshoot common issues in the [troubleshooting guide](/en/v1.57/operator-manual/ai-presets/troubleshooting)
# AI Presets Reference
Source: https://docs.zylon.ai/en/v1.57/operator-manual/ai-presets/presets
Complete reference of available AI presets including base, alternative, experimental, and deprecated configurations
Set the AI preset in your Zylon configuration file using the `ai.preset` property.
## Base Presets
Base presets provide standard configurations optimized for general-purpose AI workloads.
| Preset | Required GPU Memory | Compatible Hardware Examples | Models |
| - | - | - | - |
| `baseline-32g` | 32GB | RTX 5090 | cyankiwi/qwen3.5-9b-awq-4bit, mixedbread-ai/mxbai-embed-large-v1 |
| `baseline-48g` | 48GB | RTX A6000, A40, L40, L40s | txn545/qwen3.5-35b-a3b-nvfp4, mixedbread-ai/mxbai-embed-large-v1 |
| `baseline-96g` | 96GB | A100 80GB, H100, A6000 (dual) | cyankiwi/qwen3.5-27b-awq-4bit, mixedbread-ai/mxbai-embed-large-v1 |
### Configuration Example
```yaml theme={null}
ai:
preset: "baseline-48g" # For a system with L40s (48GB)
```
Choose the preset that matches your GPU memory capacity. Always select a preset that matches or is lower than your available VRAM.
## Alternative Presets
Zylon provides alternative presets that offer specialized configurations by trading certain capabilities for others. These are optional and should only be used when you have specific requirements that differ from the standard presets.
### Throughput-Optimized Alternative
This preset uses a smaller, lighter model that generates tokens significantly faster. While it may not match the standard model in quality and reasoning depth, it delivers noticeably faster responses in return.
**When to use:**
* You primarily handle simple or straightforward queries
* You have a high number of concurrent users and need fast response times
* Generation speed matters more than peak response quality
| Preset | GPU Memory Required | Models |
| - | - | - |
| `baseline-throughput-96g` | 96GB (A100 80GB, H100, A6000 dual) | txn545/qwen3.5-35b-a3b-nvfp4, mixedbread-ai/mxbai-embed-large-v1 |
### Large Model Alternative
This preset uses a larger, more capable model with greater intrinsic knowledge. The trade-off is a reduced context window.
**When to use:**
* You need stronger performance on complex or specialized tasks
* The model's intrinsic knowledge is a priority
* You can work with a smaller context window
| Preset | GPU Memory Required | Models |
| - | - | - |
| `baseline-large-96g` | 96GB (A100 80GB, H100, A6000 dual) | cyankiwi/qwen3.5-122b-A10b-awq-4bit, mixedbread-ai/mxbai-embed-large-v1 |
### Configuration Example
```yaml theme={null}
ai:
preset: "alternatives.baseline-throughput-96g"
```
Each alternative preset involves a trade-off. Consider your specific use case — user volume, query complexity, and context needs — before switching from the standard preset.
## Experimental Presets
Experimental presets are under active development and may not be stable. Use only in testing environments.
Experimental presets provide access to cutting-edge models and configurations that are being evaluated for future releases. These presets may have different performance characteristics or stability compared to baseline presets.
| Preset | Required GPU Memory | Model Family | Status | Models |
| - | - | - | - | - |
| `experimental.mistral-24g` | 24GB | Mistral | Beta | mistralai/mistral-small-24b-instruct-2501-awq, mixedbread-ai/mxbai-embed-large-v1 |
| `experimental.mistral-48g` | 48GB | Mistral | Beta | mistralai/mistral-small-24b-instruct-2501-awq, mixedbread-ai/mxbai-embed-large-v1 |
| `experimental.gpt-oss-24g` | 24GB | GPT-OSS | Beta | openai/gpt-oss-20b, mixedbread-ai/mxbai-embed-large-v1 |
| `experimental.gpt-oss-48g` | 48GB | GPT-OSS | Beta | openai/gpt-oss-20b, mixedbread-ai/mxbai-embed-large-v1 |
| `experimental.gpt-oss-96g` | 96GB | GPT-OSS | Beta | openai/gpt-oss-120b, mixedbread-ai/mxbai-embed-large-v1 |
| `experimental.gemma-24g` | 24GB | Gemma 3 | Alpha | google/gemma-3n-e4b-it, mixedbread-ai/mxbai-embed-large-v1 |
| `mistral-3-instruct-24g` | 24GB | Mistral | Alpha | cyankiwi/ministral-3-14b-instruct-2512-awq-4bit, mixedbread-ai/mxbai-embed-large-v1 |
| `mistral-3-instruct-48g` | 48GB | Mistral | Alpha | cyankiwi/ministral-3-14b-instruct-2512-awq-4bit, mixedbread-ai/mxbai-embed-large-v1 |
| `mistral-3-reasoning-24g` | 24GB | Mistral | Alpha | cyankiwi/ministral-3-14b-reasoning-2512-awq-4bit, mixedbread-ai/mxbai-embed-large-v1 |
| `mistral-3-reasoning-48g` | 48GB | Mistral | Alpha | cyankiwi/ministral-3-14b-reasoning-2512-awq-4bit, mixedbread-ai/mxbai-embed-large-v1 |
| `nemotron-3-nano-48g` | 48GB | Nemotron | Alpha | stelterlab/nvidia-nemotron-3-nano-30b-a3b-awq, mixedbread-ai/mxbai-embed-large-v1 |
| `glm-47-flash-32g` | 32GB | GLM | Alpha | cyankiwi/glm-4.7-flash-awq-4bit, mixedbread-ai/mxbai-embed-large-v1 |
| `glm-47-flash-48g` | 48GB | GLM | Alpha | cyankiwi/glm-4.7-flash-awq-4bit, mixedbread-ai/mxbai-embed-large-v1 |
**Configuration Example:**
```yaml theme={null}
ai:
preset: "experimental.gpt-oss-24g"
```
### Important Notes About Experimental Presets
* Experimental presets may be removed or significantly changed between versions
* Performance and stability are not guaranteed
* Not recommended for production environments
* May require additional configuration parameters
* Support may be limited
## Deprecated Presets
Deprecated presets are maintained for backward compatibility only and will not receive updates.
For customers that require older configurations, deprecated presets are available but not recommended for new installations.
| Preset | GPU Memory | Description |
| - | - | - |
| `deprecated.24g.20250710` | 24GB | Pre-Qwen 3 configuration |
| `deprecated.24g.20260327` | 24GB | Pre-Qwen 3.5 configuration |
| `deprecated.32g.20250710` | 32GB | Pre-Qwen 3 configuration |
| `deprecated.32g.20260327` | 32GB | Pre-Qwen 3.5 configuration |
| `deprecated.48g.20250710` | 48GB | Pre-Qwen 3 configuration |
| `deprecated.48g.20260327` | 48GB | Pre-Qwen 3.5 configuration |
| `deprecated.48g.20260327-context` | 48GB | Pre-Qwen 3.5 context-optimized configuration |
| `deprecated.48g.20260327-vision` | 48GB | Pre-Qwen 3.5 vision-optimized configuration |
| `deprecated.96g.20250710` | 96GB | Pre-Qwen 3 configuration |
| `deprecated.96g.20260327` | 96GB | Pre-Qwen 3.5 configuration |
| `deprecated.96g.20260327-context` | 96GB | Pre-Qwen 3.5 context-optimized configuration |
| `deprecated.96g.20260327-vision` | 96GB | Pre-Qwen 3.5 vision-optimized configuration |
| `deprecated.96g.qwen3-32b-96g` | 96GB | Pre-Qwen 3.5 Qwen 3 32B configuration |
```yaml theme={null}
ai:
preset: "deprecated.24g.20260327"
```
### Migration from Deprecated Presets
If you're using a deprecated preset, we strongly recommend migrating to current baseline or alternative presets:
1. Review the [base presets](#base-presets) to find an equivalent configuration
2. Test the new preset in a staging environment
3. Update your production configuration
4. Monitor performance and adjust if needed
Migration provides access to improved models, better performance, and ongoing support.
# Troubleshooting
Source: https://docs.zylon.ai/en/v1.57/operator-manual/ai-presets/troubleshooting
Diagnose and resolve issues with AI presets and custom configurations
## Common Issues
### Engine Fails to Start with Memory Error
**Solutions:**
1. **Verify your actual GPU memory**
```bash theme={null}
nvidia-smi
```
2. **Try the next lower preset**
```yaml theme={null}
# If using baseline-32g, try baseline-48g instead
ai:
preset: "baseline-48g"
```
3. **Remove optional capabilities to reduce memory usage**
```yaml theme={null}
# Remove capabilities
ai:
preset: "baseline-48g" # Instead of "baseline-48g,capabilities.multilingual"
```
4. **Check for other applications using GPU memory**
5. **Reboot the machine**
### Poor Performance or Slow Responses
**Solutions:**
1. **Ensure you're using the correct preset for your hardware**
2. **Consider decreasing to a lower-tier preset**
3. **Communicate with Zylon engineers to understand what is happening**
### Pod in Failed or CrashLoopBackOff State
If the Triton or inference pods are stuck in a failed state:
```bash theme={null}
# Restart the deployment
kubectl rollout restart deploy/zylon-triton -n zylon
```
This forces Kubernetes to recreate the pods with a fresh state.
***
## Advanced Issues
Issues specific to custom model configurations and multi-model setups.
### Startup Failures
#### Triton Inference Server Fails to Start
**Solutions:**
1. **Check the Triton logs to identify which specific model is causing the failure**
```bash theme={null}
kubectl logs deploy/zylon-triton -n zylon --tail=200
```
2. **Verify memory allocation for the problematic model** - adjust `gpuMemoryUtilization` if needed
3. **If you've reduced memory allocation too much, reduce the `contextWindow` parameter for that model**
4. **Use `nvidia-smi` to check actual GPU memory usage and availability**
```bash theme={null}
nvidia-smi
```
#### Unsupported Model Version
**Symptom**: Triton fails to load a model even though the model family is supported.
**Cause**: VLLM (the inference backend) may not support the specific version of your model yet. For example:
* Mistral Small 3 (2501) is supported
* Mistral Small 3 (2509) might not be supported yet
**Solutions:**
1. **Check the supported model version** in the documentation
2. **Try an earlier version** of the same model family if available
3. **Check Zylon release notes** for supported model versions
4. **Contact Zylon engineers** to confirm model compatibility
### Memory Errors
#### Engine Fails to Start with "Out of Memory" Error
**Solutions:**
1. **Verify total `gpuMemoryUtilization` does not exceed 0.95**
```yaml theme={null}
# Calculate total across all models
ai:
config:
models:
- id: llm
gpuMemoryUtilization: 0.60
- id: llmvision
gpuMemoryUtilization: 0.25
- id: embed
gpuMemoryUtilization: 0.10
# Total: 0.95 ✓
```
2. **Reduce allocation for one or more models based on the crash logs**
```bash theme={null}
kubectl logs deploy/zylon-triton -n zylon
```
3. **Check actual GPU memory with `nvidia-smi`** during startup
```bash theme={null}
watch -n 1 nvidia-smi
```
# Auditability & AI Governance
Source: https://docs.zylon.ai/en/v1.57/operator-manual/auditability-ai-safety/overview
Auditability, traceability, evidence preservation, governance, and AI accountability capabilities in Zylon.
## Overview
Auditability & AI Governance covers transparency, accountability, audit readiness, and evidence sources for Zylon deployments. It is separate from platform security: security protects the platform; auditability explains how customers can show what happened, preserve evidence, govern AI usage, and support assurance workflows.
Use this section when security, risk, compliance, legal, works-council, or audit teams need to understand what Zylon records, how evidence can be preserved, which controls are customer-configurable, and how Zylon can provide evidence for customer governance programs.
## Capability areas
| Area | What Zylon provides | Customer use |
| - | - | - |
| Auditability and traceability | Structured audit, security, backoffice, gateway, and AI lifecycle logs. | Reconstruct who acted, what was requested, what was answered, what tools were visible, and which organization or project was involved. |
| Evidence preservation | Internal log storage, retention cleanup controls, and external delivery to customer-controlled collectors. | Preserve logs for investigations, audits, legal holds, and incident response according to policy. |
| AI accountability | Chat lifecycle metadata, optional prompt/response retrieval, token usage, tools used, latency, and outcome fields. | Review AI usage, explain operational behavior, and support human oversight. |
| Operational transparency | Backoffice API retrieval, usage views, syslog delivery, HTTP delivery, and observability links. | Feed SIEM, data lake, monitoring, and audit workflows. |
| Data residency | Default log-storage behavior keeps stored logs in the customer's Zylon deployment unless external delivery is configured. | Support sovereign, on-premise, and regulated deployment requirements. |
| User rights and retention | Configurable retention and guidance for personal-data handling in logs. | Align audit retention with GDPR, works-council, legal, and data-minimization requirements. |
| Control mapping | EU AI Act, ISO 27001, SOC 2, DORA, NIS2, and GDPR evidence-mapping guidance. | Prepare procurement, risk review, and control-evidence conversations without treating Zylon logs as standalone compliance. |
## Start here
Governance view of Zylon logs, evidence preservation, data residency, control mappings, retention, and SIEM delivery.
Technical settings for internal storage, syslog delivery, HTTP delivery, filtering, queues, TLS, and retention cleanup.
Read-only retrieval endpoints for stored platform, gateway, security, workspace, backoffice, and AI usage logs.
Configure permanent deletion windows and stored-log cleanup behavior.
## Suggested governance workflow
1. Classify your AI use cases and decide which events, prompts, responses, usage metrics, and operational records must be retained.
2. Enable the required audit and logging capabilities, then configure retention windows and external delivery.
3. Send logs to a customer-controlled SIEM, archive, or data lake when independent retention or tamper-evidence is required.
4. Define who may retrieve logs with the operator role and how and when they were exported.
5. Map collected evidence to your control framework, such as EU AI Act, ISO 27001, SOC 2, DORA, NIS2, or GDPR.
6. Review retention, masking, prompt/response handling, and user-rights processes before production rollout.
## Security boundary
Security documentation remains focused on hardening the deployment: network isolation, airgap operation, encryption, access controls, and platform protection.
Auditability & AI Governance focuses on proof and accountability: traceability, evidence, monitoring, control mapping, AI usage review, and regulatory readiness. Many programs need both sections during procurement and production assurance.
# LDAP Directory Authentication
Source: https://docs.zylon.ai/en/v1.57/operator-manual/authentication/ldap
Configure Zylon to authenticate users against an LDAP directory or Active Directory, enabling centralized login without an external identity provider.
LDAP authentication lets users log in to Zylon with their existing directory credentials, whether on a standard LDAP server or Microsoft Active Directory. Because LDAP requires no connection to external identity providers like Google or Microsoft, it is the recommended authentication method for air-gapped and strictly on-prem deployments.
This page covers operator configuration only. No UI-based configuration is available; all settings are applied through the configuration file located at `/etc/zylon/zylon-conf.yaml`.
***
## Prerequisites
Before enabling LDAP, confirm the following:
* The LDAP or Active Directory host is reachable from the Zylon cluster on the port your server is configured to listen on.
* A **read-only service account** exists in the directory. Zylon uses this account (the bind account) to search for users and resolve group membership. It does not need write permissions.
* You know the **Base DN** under which all users and groups reside (e.g., `dc=company,dc=local`).
* You have the **Distinguished Names (DNs)** of any directory groups you want to map to Zylon roles.
***
## How sign-in works
When LDAP is enabled, users continue to use the standard Zylon login form. There is no separate LDAP login page.
1. The user enters their directory username in the email field and their directory password.
2. Zylon normalizes the username: a `DOMAIN\user` prefix is stripped to `user`; an email address (`user@company.com`) and a plain username (`user`) are used as-is.
3. Zylon searches the directory for the user, then performs a bind to verify the password.
4. On success, Zylon resolves the user's directory groups and maps them to Zylon roles using `roleMapping` configuration.
5. If the account does not exist in Zylon yet, it is **created automatically** with the roles derived from group membership.
Roles are assigned at account creation time. If a user's directory group membership changes after their first login, Zylon roles are not updated automatically. To change a user's roles after creation, update them through the Backoffice. See [Roles and Permissions](/en/v1.57/operator-manual/backoffice/roles-and-permissions) for details.
If LDAP is enabled and the directory is temporarily unreachable or returns an error, Zylon falls back to local credential authentication.
***
## Configuration
If LDAP is enabled and any required field is missing or invalid, the application will **refuse to start** and log a descriptive error. This prevents misconfigured deployments from silently falling.
### `/etc/zylon/zylon-conf.yaml`
Add the `auth.ldap` block to the configuration file:
The config file is a `.yaml` file, so indentation, spaces, and quotes are important. Review carefully before saving.
```yaml theme={null}
auth:
ldap:
enabled: true
host: "ldap.company.local"
port: "389"
tls:
enabled: false
caCrt: ""
caFile: ""
bindDn: "cn=LDAP Bind,ou=service,dc=company,dc=local"
bindPassword: "CHANGE_ME"
baseDn: "dc=company,dc=local"
userFilter: "(|(sAMAccountName={username})(userPrincipalName={username})(mail={username}))"
groupFilter: "(member={userDn})"
attributes:
username: "sAMAccountName"
email: "mail"
group: "memberOf"
roleMapping:
defaultRole: "Workspace"
mappings: '[{"match":"CN=admins,OU=groups,DC=company,DC=local","role":"Operator"},{"match":"CN=developers,OU=groups,DC=company,DC=local","role":"Developer"},{"match":"CN=workspace-users,OU=groups,DC=company,DC=local","role":"Workspace"}]'
```
Apply the changes:
```bash theme={null}
sudo zylon-cli sync
```
***
## Configuration reference
The table below lists every LDAP setting, its chart default, and whether it is required when `enabled` is `true`.
| Key | Default | Required | Description |
| - | - | - | - |
| `enabled` | `false` | - | Set to `true` to activate LDAP authentication. The application will not start if enabled with an invalid configuration. |
| `host` | `""` | Yes | Hostname or IP address of the LDAP or Active Directory server. |
| `port` | `"389"` | Yes | Port as a string. Must match the port your LDAP server is listening on. Common values are `389` for plain LDAP and `636` for LDAPS, but your server may be configured differently. |
| `tls.enabled` | `false` | No | Set to `true` to open an LDAPS connection |
| `tls.caCrt` | `""` | No | CA certificate as an inline string. Used to verify the LDAP server's TLS certificate. Takes precedence over `tls.caFile` if both are set. |
| `tls.caFile` | `""` | No | Path CA certificate file on the host. Used when the certificate is mounted as a file rather than passed inline. Ignored if `tls.caCrt` is set. |
| `bindDn` | `""` | Yes | Full Distinguished Name of the service account used to search the directory. Example: `cn=LDAP Bind,ou=service,dc=company,dc=local`. |
| `bindPassword` | `""` | Yes | Password for the bind account. |
| `baseDn` | `""` | Yes | Root of the directory subtree where user and group searches are performed. Example: `dc=company,dc=local`. |
| `userFilter` | `(\|(sAMAccountName={username})(userPrincipalName={username})(mail={username}))` | No | LDAP filter used to locate the user entry. Must contain `{username}`, which is replaced with the normalized login name at runtime. The default targets Active Directory and supports `sAMAccountName`, UPN, and mail formats. |
| `groupFilter` | `(member={userDn})` | No | LDAP filter used to find groups when `memberOf` is not populated on the user entry. Must contain `{userDn}`. |
| `attributes.username` | `sAMAccountName` | No | Directory attribute to use as the Zylon display name. |
| `attributes.email` | `mail` | No | Directory attribute to use as the Zylon account email. This attribute must be present on every user entry; if it is missing, login is rejected. |
| `attributes.group` | `memberOf` | No | Directory attribute on the user entry that lists group membership. If this attribute is absent or empty, Zylon falls back to a separate group search using `groupFilter`. |
| `roleMapping.defaultRole` | `Workspace` | No | Role assigned to a user when no group mapping matches. Valid values: `Workspace`, `Developer`, `Operator`. |
| `roleMapping.mappings` | `""` | No | Stringified JSON array of group-to-role mappings. See [Role mapping](#role-mapping) below. When empty, all users receive `defaultRole`. |
## Role mapping
Group-to-role mapping is defined as a **stringified JSON array** in the `roleMapping.mappings` field. The value must always be a JSON-encoded string, both in `values.yaml` and in `zylon-conf.yaml`. Zylon evaluates the mapping at login time and assigns roles based on the directory groups the user belongs to.
```yaml theme={null}
roleMapping:
mappings: '[{"match":"CN=admins,OU=groups,DC=company,DC=local","role":"Operator"},{"match":"CN=developers,OU=groups,DC=company,DC=local","role":"Developer"},{"match":"CN=workspace-users,OU=groups,DC=company,DC=local","role":"Workspace"}]'
```
**Matching behaviour:**
* Each `match` value is compared against every group DN the user belongs to. The comparison is case-insensitive.
* If a user belongs to multiple mapped groups, they receive all matching roles.
* If no mapping matches, the user receives `defaultRole`.
* Multiple groups can map to the same role; duplicates are collapsed.
For a complete description of what each role can do, see [Roles and Permissions](/en/v1.57/operator-manual/backoffice/roles-and-permissions).
Roles are computed once at account creation (first login). Subsequent changes to directory group membership are not reflected in Zylon automatically. Update roles manually through the Backoffice if needed.
***
## Active Directory notes
The default configuration targets Active Directory out of the box:
* `userFilter` accepts logins in three formats: plain username (`jdoe`), UPN (`jdoe@company.com`), and Windows domain format (`DOMAIN\jdoe`, normalized to `jdoe` before the search).
* `attributes.username` defaults to `sAMAccountName` and `attributes.email` to `mail`, matching standard AD schemas.
* Group membership is read from the `memberOf` attribute on the user entry.
For standard LDAP servers (OpenLDAP, 389 Directory Server, etc.) you will typically need to adjust `userFilter`, `groupFilter`, and `attributes.*` to match your schema. A common starting point:
```yaml theme={null}
userFilter: "(uid={username})"
groupFilter: "(member={userDn})"
attributes:
username: "uid"
email: "mail"
group: "memberOf"
```
***
## Verify the configuration
After applying the configuration, follow these steps to confirm LDAP is working correctly:
Check the backend pod is running. If a required field is missing, the service will not start and will log the specific field that failed validation.
Log in to the Zylon workspace with a directory user account. Use the username or email address format your directory supports.
Open the Backoffice and locate the newly created account. Confirm it has the expected roles based on the user's group membership and the `roleMapping` configuration.
Repeat the test for at least one user per mapped group (Operator, Developer, Workspace) to confirm the role mapping is working correctly across all groups.
***
## Troubleshooting
| Symptom | Likely cause | What to check |
| - | - | - |
| Application does not start | Required field missing or `port` is not a valid integer | Check logs for the specific validation error; confirm `host`, `baseDn`, `bindDn`, `bindPassword`, and `port` are all set |
| Login fails for a valid directory user | Unreachable server, wrong `bindPassword`, or `userFilter` does not match the user entry | Verify network connectivity on the configured port; test the bind account credentials with an LDAP client; review `userFilter` |
| "Ambiguous LDAP user" error on login | `userFilter` returns more than one directory entry for the username | Tighten the filter to target a unique attribute, or remove overlapping login format matchers |
| Login succeeds but user has the wrong role | Group DN in `roleMapping.mappings` does not match the actual group DN (check for typos, OU differences, or casing) | Compare the `match` values against the exact group DNs in your directory; matching is case-insensitive but the DN structure must be correct |
| Login succeeds but user has `defaultRole` only | No group mapping matched, or `mappings` is empty | Check that `memberOf` is populated on the user entry; verify the JSON syntax of `mappings` |
| LDAP user cannot log in - missing email | The `mail` (or configured `attributes.email`) attribute is absent on the directory entry | Populate the email attribute for the user in the directory, or update `attributes.email` to point to a different attribute that is present |
| Users appear to log in with local credentials despite LDAP being enabled | LDAP returned an error (server unreachable, bad bind password), triggering a fallback | Check server connectivity and bind account credentials; review backend logs for the LDAP error that caused the fallback |
***
## Security considerations
* Use a **read-only, least-privilege** service account for the bind credentials. The account needs search permission on users and groups under `baseDn`, nothing more.
* Enable `tls.enabled: true` to encrypt credentials in transit. Provide `tls.caCrt` or `tls.caFile` to pin your CA.
* Directory group membership changes are not reflected in Zylon after account creation. Operators must update roles manually in the Backoffice if group membership changes.
For air-gapped deployments, LDAP requires no outbound internet access. See [Airgap Your Server](/en/v1.57/operator-manual/instance-hardening/airgap-your-server) for firewall configuration guidance.
# Accessing the Backoffice
Source: https://docs.zylon.ai/en/v1.57/operator-manual/backoffice/accessing-the-backoffice
Open the Backoffice from a Workspace or a direct URL.
There are two ways to access the Backoffice. Both require an account with **Operator** or **Developer** permissions.
1. **From Workspace navigation**
Open the left navigation menu and select **Platform Backoffice** or **Developer Console**. These entries appear only when your account has the required role.
2. **From a direct URL**
Navigate to `https:///backoffice`. You will be redirected to the Backoffice login page.
Sign in using:
* Zylon account credentials, or
* an enabled SSO provider (for example, Google or Microsoft)
After signing in, you can switch between **Platform Backoffice**, **Developer Console**, and **Workspace**.
# Guardrails
Source: https://docs.zylon.ai/en/v1.57/operator-manual/backoffice/guardrails
Create regex-based guardrails and assign them to gateways to block AI requests that match sensitive patterns.
## Overview
**Guardrails** let Operators define rules that inspect AI traffic flowing through a gateway. When a guardrail is triggered, the AI request is **blocked** before it reaches the model.
Guardrails are useful to prevent sensitive or non-compliant data (such as national IDs, bank accounts, or credit cards) from being sent to the AI, helping you enforce data protection and compliance policies.
Each guardrail is:
* **Assigned to one or more gateways**, so it only applies to the traffic of those gateways.
* **Evaluated on every AI request** handled by the assigned gateways.
* **Blocking**: when the guardrail matches, the request is rejected.
For now, guardrails support **regular expressions (regex)** only. Additional guardrail types may be added in the future.
Only users with the **Operator** role can manage guardrails. Availability and limits depend on the active license.
## How guardrails work
A guardrail contains one or more **regex patterns**. On each AI request routed through an assigned gateway:
1. The request content is checked against the guardrail's regex patterns.
2. If **any** pattern matches, the guardrail is triggered.
3. The AI request is **blocked** and does not reach the model.
Because regex guardrails run locally as a text match, they add virtually no latency to the request.
## Create a guardrail
To create a guardrail:
1. Open **Guardrails** in the Platform Backoffice.
2. Click **Add guardrail**.
3. Enter a **name** and an optional **description**.
4. Select the **gateways** this guardrail should apply to.
5. Add one or more **regex** patterns. Use **Add regex** to define multiple patterns in the same guardrail.
6. Save the guardrail.
Once saved, the guardrail is active on every assigned gateway and starts blocking matching requests immediately.
## Manage guardrails
From the guardrails list you can review each guardrail's name, description, type, effect, and the gateways it is assigned to.
* **Edit** a guardrail to update its patterns or reassign it to different gateways.
* **Delete** a guardrail to stop it from blocking requests.
## Regex examples
The table below lists common regex patterns you can use as a starting point for your guardrails. Adjust them to match the exact formats used in your organization.
| Data type | Example regex |
| - | - |
| Spanish DNI | `\b\d{8}[A-Za-z]\b` |
| Spanish NIE | `\b[XYZ]\d{7}[A-Za-z]\b` |
| IBAN (bank account) | `\b[A-Z]{2}\d{2}[A-Z0-9]{11,30}\b` |
| Spanish CCC (bank account) | `\b\d{4}[ -]?\d{4}[ -]?\d{2}[ -]?\d{10}\b` |
| Credit card number | `\b(?:\d[ -]?){13,16}\b` |
| Email address | `\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b` |
| Phone number (Spain) | `(?:\+34\|0034)?[ -]?[6-9]\d{2}[ -]?\d{3}[ -]?\d{3}` |
| Spanish social security number | `\b\d{2}[ -]?\d{8}[ -]?\d{2}\b` |
| IPv4 address | `\b(?:\d{1,3}\.){3}\d{1,3}\b` |
### Copy-ready regex snippets
Use the code blocks below when you want a one-click copy action.
#### Spanish DNI
```txt theme={null}
\b\d{8}[A-Za-z]\b
```
#### Spanish NIE
```txt theme={null}
\b[XYZ]\d{7}[A-Za-z]\b
```
#### IBAN
```txt theme={null}
\b[A-Z]{2}\d{2}[A-Z0-9]{11,30}\b
```
#### Spanish CCC
```txt theme={null}
\b\d{4}[ -]?\d{4}[ -]?\d{2}[ -]?\d{10}\b
```
#### Credit card number
```txt theme={null}
\b(?:\d[ -]?){13,16}\b
```
#### Email address
```txt theme={null}
\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b
```
#### Phone number (Spain)
```txt theme={null}
(?:\+34|0034)?[ -]?[6-9]\d{2}[ -]?\d{3}[ -]?\d{3}
```
#### Spanish social security number
```txt theme={null}
\b\d{2}[ -]?\d{8}[ -]?\d{2}\b
```
#### IPv4 address
```txt theme={null}
\b(?:\d{1,3}\.){3}\d{1,3}\b
```
Regex patterns are matched exactly as written. Always test your patterns against representative data to avoid false positives (blocking valid requests) or false negatives (letting sensitive data through).
# Introduction
Source: https://docs.zylon.ai/en/v1.57/operator-manual/backoffice/introduction
Overview of the Zylon Backoffice.
The Zylon Backoffice is the centralized administration environment for managing the Zylon platform. It is separated from Workspace and is used for Platform administration and API development operations.
Backoffice capabilities include:
* Account management
* Role and permission management
* Gateway management
* API token management
* Platform service status monitoring
Backoffice access requires a valid account with the appropriate role:
* **Operator** role for platform administration
* **Developer** role for API token workflows
Users can hold multiple roles on the same account. Features are made available based on the roles assigned to that account.
Operator controls for accounts, roles, gateways, and service status.
Monitor AI usage across gateways, API tokens, and Workspace activity.
Understand account roles, gateway roles, and access levels.
Create accounts, assign roles, and manage access.
Manage isolated software nodes for API development.
Understand auditability, traceability, evidence preservation, storage, SIEM delivery, and operational access.
Create and manage API tokens by gateway.
Generate and securely store a one-time token secret.
# Logging, Evidence, and SIEM Delivery
Source: https://docs.zylon.ai/en/v1.57/operator-manual/backoffice/log-delivery-storage
Governance guide to Zylon logging, evidence preservation, auditability, traceability, and SIEM delivery.
## Overview
Zylon records structured audit, security, application, and AI chat lifecycle events when logging storage or delivery is enabled. Operators can use these logs to investigate what happened, who initiated it, what was requested, what was answered, and which observable tools or data paths were used.
Zylon can:
* Store structured logs internally when logging storage is enabled.
* Send logs to SIEM applications and log collectors using supported syslog formats, including RFC 5424 JSON and CEF.
* Send structured JSON logs to HTTP destinations, including cloud-based ingestion endpoints and customer-managed collectors.
* Let authorized Backoffice users retrieve stored logs manually.
**Default log-storage behavior keeps stored logs inside the customer's Zylon deployment unless external log delivery is configured.** Operators should confirm deployment-specific observability, telemetry, and crash-reporting settings separately.
External delivery configuration is documented in [Configuration: Log Delivery and Storage](/en/v1.57/operator-manual/configuration/features/log-delivery-storage).
External delivery is asynchronous. With the default `failurePolicy=drop`, delivery is designed to stay off the critical request path when queues are under pressure.
## Before you configure delivery
* Confirm which logs must be stored in Zylon and which logs must be delivered to customer-controlled systems.
* Confirm the syslog collector host and port, or the HTTP collector URL, from the Zylon deployment network.
* Select syslog `rfc5424_json`, syslog `cef`, or HTTP `canonical_json` according to the collector input.
* Decide whether TLS certificate verification is required and prepare a trusted CA path when needed.
* Decide retention in both Zylon internal storage and downstream systems.
* Review action and organization filters so required audit events are not excluded.
* Confirm all Zylon nodes use a trusted time source such as NTP. Log timestamps are most useful for forensic correlation when host clocks are synchronized and reviewed in UTC.
## What Zylon logs
Zylon stores a shared log envelope and event-specific structured data. Exact fields depend on the event family and enabled logging settings.
| Category | Examples of fields stored | Why it matters |
| - | - | - |
| Actor context | User, account, token, and actor type identifiers | Helps determine who or what initiated an action. |
| Organization and project context | Organization, gateway, and project identifiers | Helps scope investigation to a workspace, gateway, or project. |
| AI chat context | Request, response, token, latency, and tool-use metadata when audit logging captures it | Helps reconstruct observable chat lifecycle when stored. |
| Agent-visible actions | Tools, integration actions, artifact actions, chat actions, and project actions | Helps understand what the agent or user-visible workflow used. |
| Security and audit events | Authentication failures, invalid or expired tokens, malformed auth headers, account creation, login, password reset/change, API token create/delete, log retrieval | Supports security review and access monitoring. |
| Timing and outcome | Start time, end time, error, outcome, and severity | Helps correlate events and identify failed or risky activity. |
| Delivery metadata | External delivery schema, severity, outcome, actor, environment for syslog records | Helps SIEM and collector pipelines classify delivered events. |
Sensitive request keys are masked before request input payloads are stored. Masked values are stored as `***`; they are not hashed, tokenized, or preserved as last-four characters in Zylon logs. URI user information in primitive string values is also redacted before storage.
Zylon masks these exact request-key names before storage: `password`, `new_password`, `current_password`, `secret`, `api_key`, `apikey`, `private_key`, `privatekey`, `token`, `id_token`, `access_token`, `refresh_token`, `session_token`, `bearer_token`, `client_secret`, `secret_key`, `credentials`, `connection_string`, `cookie`, `set_cookie`, and `authorization`.
Zylon also masks keys ending in `_token`, `_password`, `_secret`, `_credential`, `_credentials`, `_connection_string`, or `_cookie`.
## Trust and integrity
Stored logs should be treated as operational audit records with a read-only Backoffice retrieval surface:
* Documented Backoffice log access is for retrieval only.
* Log retrieval through Backoffice is itself logged, so operators can review who accessed platform or gateway log records.
* No documented Backoffice UI or API flow permits an operator to modify or delete one stored log record.
* The documented deletion path for stored log records is the configured retention cleanup task.
* Cleanup is disabled by default. When cleanup is enabled, the default stored log retention threshold is `180` days.
Zylon does not document a cryptographic hash chain, signature chain, or tamper-evident log store for internal records. For stronger tamper-evidence, deliver logs to a customer-controlled SIEM or append-only archive, restrict database administrator access, retain backups, and monitor Kubernetes/database audit trails. Direct database access by infrastructure administrators is outside the Backoffice permission model and should be governed by the customer's platform controls.
### Logging-system administration
Logging storage, retention, syslog delivery, and HTTP delivery are deployment configuration settings. Changes such as disabling storage, reducing retention, or changing delivery destinations should be captured in the customer's change-management system, GitOps history, Kubernetes audit trail, or infrastructure audit logs.
## AI auditability
Zylon provides auditability of the observable chat lifecycle and agent-visible actions. Logs can support reconstruction of:
* who initiated a chat;
* which organization, gateway, or project was involved;
* what request metadata was stored;
* what response was stored when audit logging captured it;
* which tools were visible in the response payload;
* which actions, integrations, files, chats, and projects were used.
Zylon logs observable inputs, outputs, actions, tools, data paths, actors, and system events. It does not expose proprietary or private internal reasoning unless that reasoning was explicitly emitted and stored as part of the response.
## EU AI Act-supporting logging and traceability
Zylon logging can support EU AI Act traceability and record-keeping workflows, depending on configuration and deployment. It should be treated as one technical evidence source inside a broader governance, monitoring, and retention program.
Relevant official EU AI Act Service Desk pages:
* [Article 12: Record-keeping](https://ai-act-service-desk.ec.europa.eu/en/ai-act/article-12)
* [Article 19: Automatically generated logs](https://ai-act-service-desk.ec.europa.eu/en/ai-act/article-19)
* [Article 26: Obligations of deployers of high-risk AI systems](https://ai-act-service-desk.ec.europa.eu/en/ai-act/article-26)
| EU AI Act-related theme | How Zylon logging can support it | Customer responsibility |
| - | - | - |
| Automatic event logging | Zylon records configured audit, security, application, and AI chat lifecycle events. | Enable storage or delivery for the required events and confirm coverage for the deployed use case. |
| Traceability | Logs help reconstruct actors, timestamps, prompts or request data when stored, responses when included, tools, gateway, organization, and project context. | Maintain access controls, preserve downstream correlation IDs, and decide which fields must be retained. |
| Operation monitoring | Logs can be reviewed through Backoffice log retrieval or delivered to SIEM/syslog/HTTP collectors. Log retrieval activity is also logged for follow-up review. | Configure monitoring, alerts, reviews, and escalation processes. |
| Investigation | Logs support incident review and reconstruction across user, token, workspace, security, and AI lifecycle events. | Preserve and correlate Zylon logs with customer infrastructure, identity, network, and SIEM records. |
| Retention | Zylon can clean up stored logs after a configured retention window. The application default is `180` days when logging cleanup is enabled. | Keep retention aligned with legal, security, and operational requirements, and confirm downstream collector retention separately. |
This documentation is not legal advice. Customers are responsible for determining whether their deployment is subject to the EU AI Act or other laws, which role they occupy, and what logging, monitoring, and retention controls are required.
## Control evidence mapping
This table is a procurement and control-evidence aid, not a certification statement or compliance claim. Final applicability depends on the customer's deployment, policies, procedures, monitoring, retention, and use case.
| Framework or rule | Logging expectation | Zylon supports |
| - | - | - |
| ISO/IEC 27001:2022 A.8.15 | Log events relevant to user activity, exceptions, faults, and information security events. | Structured workspace, security, backoffice, gateway, and AI lifecycle logs can be stored internally or delivered externally. |
| ISO/IEC 27001:2022 A.8.16 | Monitor activities and logs to detect anomalous behavior and incidents. | Syslog and HTTP delivery support SIEM ingestion, alerting, and customer monitoring workflows. |
| SOC 2 CC7.2 | Monitor system components and detect anomalies that may indicate malicious activity. | Security/auth events, token events, account events, and gateway usage logs can feed detection and investigation processes. |
| DORA Article 17 | Record, classify, and manage ICT-related incidents. | Logs provide incident reconstruction inputs across actor, organization, project, request, response, timing, and outcome fields when configured. |
| NIS2 | Support incident detection, response, and evidence preservation. | Customer-controlled delivery and retention can preserve logs for security operations and reporting workflows. |
| GDPR Article 30 | Maintain records of processing activities. | Logs can help identify actors, systems, and processing context, but the customer remains responsible for records of processing. |
| GDPR Article 32 | Protect confidentiality, integrity, availability, and resilience. | Access control, masking, retention, TLS delivery, and SIEM forwarding can support security-of-processing controls. |
| GDPR Article 33 | Notify supervisory authority after qualifying personal data breaches. | Logs can support breach investigation timelines, affected systems, and evidence gathering. |
## Log storage and retention
When logging storage is enabled, Zylon persists structured logs in internal storage. When logging storage is disabled, new logs are not persisted internally.
Zylon can clean up stored logs after a configured retention window. Stored log cleanup is disabled by default. The default retention value is `180` days once logging cleanup is enabled. The cleanup task deletes stored log records older than the configured threshold.
External collectors keep their own retention policies outside Zylon.
| Storage location | Who controls retention | Notes |
| - | - | - |
| Zylon internal log storage | Deployment operator and cleanup configuration | Storage is enabled by default. Logging cleanup default is `180` days when enabled. |
| Customer SIEM or syslog collector | Customer | Controlled by collector input, index, archive, and deletion policy. |
| Customer HTTP collector or data lake | Customer | Controlled by downstream ingestion, transformation, and storage policy. |
Confirm downstream retention separately from Zylon storage. Zylon cannot guarantee retention in customer-managed SIEM, syslog, HTTP collector, or data lake systems.
### Right to erasure and retention
Audit and security logs may contain user identifiers, account identifiers, organization identifiers, IP addresses, prompts, responses, or other context that can be personal data depending on the deployment. A user deletion or erasure workflow does not automatically imply immediate deletion of every historical audit record; many regulated environments retain security logs for a defined period to preserve fraud, abuse, and incident evidence.
Set stored-log retention, external delivery filters, and downstream collector retention according to your legal basis and data-minimization policy. If your policy requires pseudonymization or earlier deletion of user-linked log fields, implement that requirement in the customer-controlled collector/SIEM or validate product behavior for the deployed version before enabling long retention.
## Time and schema markers
Backoffice log records expose ISO timestamps such as `start_timestamp` and `end_timestamp`. Use UTC for cross-system investigation and keep all Zylon nodes synchronized with NTP or an equivalent trusted time source.
Delivered payloads include schema markers such as `zylon.rfc5424_json.v1` and `zylon.canonical_json.v1`. These markers let SIEM parsers route and identify payload shapes. They do not, by themselves, enforce a deprecation or migration policy; validate parser compatibility when upgrading.
## Ways to consume logs
| Access method | Use when | Documentation |
| - | - | - |
| Backoffice UI | Operators need interactive usage review. The Backoffice UI shows data exposed through the `/usage` endpoint. | [Platform Backoffice](/en/v1.57/operator-manual/backoffice/platform-backoffice) |
| Backoffice API: Logging | Authorized users need manual retrieval, export scripts, or integration jobs. | [Logging](/en/v1.57/developer-manual/build-with-zylon/backoffice-api/logging) |
| Syslog delivery | Customer SIEM or syslog collector should receive events. | [Log Delivery and Storage configuration](/en/v1.57/operator-manual/configuration/features/log-delivery-storage#syslog-delivery) |
| HTTP delivery | Customer ingestion gateway or custom pipeline should receive structured JSON. | [Log Delivery and Storage configuration](/en/v1.57/operator-manual/configuration/features/log-delivery-storage#http-delivery) |
## Operational recommendations
* Keep internal log storage enabled unless security, legal, and operations teams approve disabling it.
* Deliver logs to a customer-controlled SIEM or collector where long-term monitoring or independent retention is required.
* Prefer TLS for syslog where supported by the collector.
* Enable certificate verification in production when the collector has a trusted certificate path.
* Use filters carefully so required investigation events are not excluded.
* Confirm retention in downstream systems separately from Zylon internal storage.
* Test retrieval and delivery after changing logging configuration.
# Platform Backoffice
Source: https://docs.zylon.ai/en/v1.57/operator-manual/backoffice/platform-backoffice
Operator controls for accounts, roles, gateways, and service status.
## Overview
The Platform Backoffice is used by Operators to manage platform-level access and developer environments.
From this section, Operators can:
* Create and manage accounts
* Assign and update account roles
* Create and manage gateways
* Monitor platform service status
Only users with **Operator** role can access this section. Permissions, visibility, and limits depend on the active license.
## Accounts
An **Account** represents one person on the Zylon platform. Accounts define platform access and determine which Backoffice sections are available.
### Roles and permissions
Account roles define platform-level access:
* **Super Admin** and **Operator** roles can access platform administration features.
* **Developer** role can access Developer Console.
* **Workspace** role does not grant Platform Backoffice access.
For the full role matrix and permission model, see [Roles and Permissions](/en/v1.57/operator-manual/backoffice/roles-and-permissions).
### Create an account
You can create users in two ways.
1. **Create from the modal UI**
* Click **Add account**.
* Enter name (optional), email, and password.
* Assign one or more account roles.
* Save the account.
2. **Create in bulk from CSV**
* Download the CSV template available on the Accounts page.
* Fill the template with user details and role assignments.
* Upload the CSV to create multiple accounts.
### Edit accounts and role assignments
To update an account, open the account from the list and modify its role assignments or details.
Use role assignment to control whether an user can:
* Access Backoffice Platform.
* Access Workspace.
* Access Developer Console.
The number of accounts and role-enabled accounts is controlled by the active license.
## Gateways
A **Gateway** is a dedicated, isolated software service that sits at the boundary between clients and Zylon’s internal APIs. It provides a single, controlled entry point for API development handling concerns request routing, authentication/authorization, traffic, and observability.
Gateways are used to:
* Group API development activity limiting access to vector database only for vectors belonging to the gateway
* Control who can work with tokens in each environment
* Log account usage and token usage for that gateway
### Gateway user roles
Accounts with the **Developer** and **Operator** roles can be assigned a gateway role: **Owner**, **Admin**, or **Member**.
For gateway-role capabilities, see [Roles and Permissions](/en/v1.57/operator-manual/backoffice/roles-and-permissions).
### Create a gateway
To create a gateway:
1. Open **Gateways**.
2. Click **New gateway**.
3. Enter a gateway name.
4. Click **Create**.
### Manage gateways
From the gateway list, Operators can open existing gateways to manage users and maintain the gateway configuration used by development teams.
The total number of gateways is limited by the active license.
# Roles and Permissions
Source: https://docs.zylon.ai/en/v1.57/operator-manual/backoffice/roles-and-permissions
Backoffice roles, access levels, and responsibilities.
## Overview
Backoffice access is role-based. What a user can see and do depends on:
1. The **account role** assigned in Backoffice.
2. The **gateway role** assigned inside each gateway.
A single account can have more than one role.
## Account roles
Account roles define platform-level access.
| Account role | What this role does | Backoffice access |
| - | - | - |
| **Super Admin** | Initial administrative account for platform setup and governance | Same platform access as **Operator** |
| **Operator** | Manages accounts, roles, gateways, and platform operations | Full **Platform Backoffice** access |
| **Developer** | Works with gateways and API tokens for development | Access to **Developer Console** |
| **Workspace** | Uses Workspace for projects and collaboration | No Platform Backoffice access |
## Gateway roles
Gateway roles define what a user can do inside a specific gateway.
| Gateway role | What this role does |
| - | - |
| **Owner** | Manages gateway users and roles, creates and manages tokens |
| **Admin** | Manages gateway users, creates and manages tokens |
| **Member** | Creates and manages own tokens |
## How access works in practice
* **Account role** controls which Backoffice sections are available.
* **Gateway role** controls actions inside each gateway.
* An **Operator** who enters gateway workflows uses the same gateway-role permissions as any other gateway user.
* Permissions are always scoped to the current role and context.
# Usage Dashboard
Source: https://docs.zylon.ai/en/v1.57/operator-manual/backoffice/usage-dashboard
Monitor AI usage across gateways, API tokens, and Workspace activity.
## Overview
The Usage Dashboard gives Operators a centralized view of AI usage across the Zylon platform. It helps answer operational questions such as how much token consumption is happening, which gateways are active, and whether knowledge, file, and web-search activity is being used.
Use the dashboard when you need to:
* Monitor AI usage over time.
* Compare total usage with per-gateway usage.
* Review usage for one or more gateways.
* Inspect activity associated with API tokens.
* Understand how Workspace activity contributes to platform usage.
The dashboard is available from **Backoffice > Platform > Usage** for users with **Operator** access. Usage metrics require [Audit Log](/en/v1.57/operator-manual/configuration/features/feat-audit) logging and storage to be enabled.
## Understanding usage collection
Workspace and API Token requests are routed through a Gateway. Each Gateway records the usage it handles, so the Usage Dashboard reports activity by Gateway.
Workspace requests use Workspace sessions instead of API Tokens. They appear in Gateway totals when **Keys** is set to **All tokens**, but they do not appear when filtering by a specific API Token.
![Usage Dashboard in Backoffice]()
## Available information
The dashboard shows summary cards and charts for the selected filters.
### Token usage metrics
**Total tokens in** is the total number of input tokens consumed by chat requests in the selected date range and Gateway scope.
Use this metric to understand the amount of user, system, and context input being sent to AI providers.
**Total tokens out** is the total number of output tokens generated by chat responses in the selected date range and Gateway scope.
Use this metric to understand how much AI-generated response content is being produced.
The **Token usage** chart shows total chat token consumption over time. It combines input and output tokens for each day in the selected date range.
When **Group by** is set to **All Gateways**, the chart shows one combined total. When **Group by** is set to **Gateways**, the chart breaks the same total into one series per selected gateway.
The **Files ingested** chart shows the number of unique files ingested over time.
This helps Operators confirm whether knowledge ingestion is happening and when ingestion activity occurred.
The **Embeddings** chart shows embedding activity over time. Each recorded embedding event is counted once.
Use this chart to understand when embedding workloads are occurring.
### Tool execution metrics
The **File searches** chart shows file-search tool usage found in chat activity.
Use this chart to understand when users or applications are asking Zylon to search available knowledge and files during AI interactions.
The **Web searches** chart shows web-search tool usage found in chat activity.
Use this chart to understand when AI interactions are using web search.
## Filters
Filter state is kept in the page URL, so a filtered view can be refreshed or shared with another authorized Backoffice user.
**Group by** controls how charts are displayed.
* **All Gateways** shows one combined total series.
* **Gateways** breaks charts down by gateway.
This filter changes chart grouping only. It does not change which usage records are included.
**Show** controls the gateway scope.
* **All** includes all available gateways.
* Selecting one or more gateways limits the dashboard to those gateways.
When **Show** changes, **Keys** resets to **All tokens**. This prevents a token selection from a previous gateway scope from remaining active after the gateway scope changes.
**Keys** filters API Token activity for the currently selected gateways.
* **All tokens** includes all usage in the selected gateway scope, including Workspace-generated usage.
* Selecting one or more API tokens shows only usage associated with those API tokens.
Workspace-generated usage is not associated with an API token. Because of that, Workspace activity appears when **Keys** is set to **All tokens**, but it does not appear when filtering by a specific API token.
**Date range** controls the time period shown by the dashboard.
Available presets are:
* **Week to date**
* **Month to date**
* **Last 7 days**
* **Last 14 days**
* **Last 30 days**
The default date range is **Last 14 days**. You can also select a custom range. Future dates are not available, and the calendar starts at **January 1, 2026**.
If a custom range is entered with the end date before the start date, Zylon normalizes the range.
## Notes and limitations
* The dashboard is read-only. It does not create, edit, or delete platform data.
* Export and download controls are not available from this dashboard.
* Filters by organization, project, user, or account email are not available.
* If no gateways are available, the dashboard shows an empty state.
* If gateways exist but no usage matches the selected filters, charts show a no-data state.
* Usage metrics depend on audit logging and storage. If storage is disabled, the dashboard cannot render usage metrics.
* The dashboard depends on stored application log data. If log records are removed by the cleanup schedule in [Cron tasks > Hard Delete](/en/v1.57/operator-manual/configuration/cron-tasks/hard-delete), or by the organization's retention policy, the dashboard cannot show usage for the removed records.
* Stored usage is most useful when system clocks are synchronized across the deployment.
# Zylon CLI
Source: https://docs.zylon.ai/en/v1.57/operator-manual/configuration/cli
All the commands available in the CLI
## admin-password
Get a one-time login password for the admin user
Usage: `sudo zylon-cli admin-password`
Calls the backend to generate a temporary password for `admin@zylon.ai` and prints it to stdout. Use this after running `seed` to obtain the initial admin login password.
## backup
Create a backup
Usage: `sudo zylon-cli backup --help`
**Flags:**
* `-o, --backup-dir`: Path to the backup dir (default: `/var/backups/zylon`)
* `-k, --keep-last`: Number of backups to keep (default: `10`)
* `-u, --unsafe`: Do not stop k0s before taking the backup. Use only when avoiding downtime is more important than data safety (for example in non-production or test environments), as this may lead to data corruption and is not recommended for production backups.
* `-y, --yes`: Skip user confirmation
## completion
Generate the autocompletion script for the specified shell
Usage: `sudo zylon-cli completion`
## config
Manage configuration
Usage: `sudo zylon-cli config`
## create-api-token
Create an API token for Zylon
Usage: `sudo zylon-cli create-api-token`
## doctor
Check the health of Zylon setup
Usage: `sudo zylon-cli doctor`
## download
Download a specific version of Zylon
Usage: `sudo zylon-cli download --help`
**Flags:**
* `--airgap`: Enable airgap mode (installs everything)
* `--arch`: Target CPU architecture
* `--binaries`: Install portable binaries
* `--drivers`: Install NVIDIA drivers
* `--force`: Force reinstallation of existing components
* `--images`: Install container images
* `--models`: AI models (can be specified multiple times or comma-separated) (default: `[]`)
* `--os`: Target OS (ubuntu22, ubuntu24)
* `--packages`: Install APT packages
* `--source`: Source to download artifacts from (s3 or source) (default: `s3`)
## export
Export a specific version of Zylon artifacts
Usage: `sudo zylon-cli export --help`
**Flags:**
* `--arch`: Target architecture
* `--from`: Base version for incremental export (exports only differences)
* `--models`: AI models (can be specified multiple times or comma-separated) (default: `[]`)
* `--no-binaries`: Exclude portable binaries
* `--no-cluster-chart`: Exclude cluster Helm charts
* `--no-drivers`: Exclude NVIDIA drivers
* `--no-images`: Exclude container images
* `--no-packages`: Exclude APT packages
* `--no-zylon-chart`: Exclude Zylon Helm charts
* `--os`: Target operating system
* `--output`: Output tar or tar.gz file path (defaults to zylon---.tar)
* `--yes`: Skip user confirmation
## forge
Forge models for Zylon
Usage: `sudo zylon-cli forge`
## forward
Forward a command to a running service
Usage: `sudo zylon-cli forward --help`
**Flags:**
* `-a, --args`: Arguments to pass to the command
* `-c, --command`: Command to run
* `-s, --service`: Service name
## help
Help about any command
Usage: `sudo zylon-cli help`
## import
Import Zylon artifacts from a tar or tar.gz archive
Usage: `sudo zylon-cli import`
## install
Install Zylon with the current configuration
Usage: `sudo zylon-cli install --help`
**Flags:**
* `--airgap`: Enable airgap mode (installs everything)
* `--force`: Force reinstallation of existing components
* `--images`: Install container images
* `--models`: AI models (can be specified multiple times or comma-separated) (default: `[]`)
* `--no-binaries`: Exclude portable binaries
* `--no-cluster-chart`: Exclude cluster Helm charts
* `--no-drivers`: Exclude NVIDIA drivers
* `--no-packages`: Exclude APT packages
* `--no-zylon-chart`: Exclude Zylon Helm charts
* `--skip-final-checks`: Skip final checks after installation
* `--skip-migrations`: Skip running migrations before installation
* `--skip-preflight`: Skip preflight checks before installation
* `--source`: Source to download artifacts from (s3 or source). Only applicable in non-airgap mode (default: `s3`)
## install-drivers
Install NVIDIA drivers
Usage: `sudo zylon-cli install-drivers --help`
**Flags:**
* `-f, --force`: Force install drivers
## list-versions
List the currently installed Zylon version
Usage: `sudo zylon-cli list-versions --help`
**Flags:**
* `--changelog`: Show changelog links (default: `true`)
* `--offline`: Indicate offline installation (no S3 access)
## preflight
Execute preflight checks
Usage: `sudo zylon-cli preflight --help`
**Flags:**
* `--fresh-system`: Validate fresh system installations
* `--network`: Validate network access to required domains (for semi-airgap installations)
* `-v, --verbose`: Enable verbose output with detailed information
## restart
Restart Zylon services
Usage: `sudo zylon-cli restart`
## restore
Restore from a backup
Usage: `sudo zylon-cli restore --help`
**Flags:**
* `-f, --backup-file`: Path to the backup tar file. If empty, defaults to the latest backup
## run-sql
Run SQL commands against Zylon's database
Usage: `sudo zylon-cli run-sql --help`
**Flags:**
* `--db`: Target database (default is 'main') (default: `main`)
* `-f, --file`: Path to a file containing SQL commands to execute
* `-s, --sql`: SQL command to execute
## seed
Seed the database
Usage: `sudo zylon-cli seed --help`
**Flags:**
* `-e, --email-regex`: All emails matching this regex will be allowed to join the organization. Usually this would be .\*@.yourdomain.com
* `-o, --org-name`: Organization name
After seeding, run `sudo zylon-cli admin-password` to retrieve the one-time login password for `admin@zylon.ai`.
## self-update
Update the CLI
Usage: `sudo zylon-cli self-update`
## sync-kube-config
Sync kube config
Usage: `sudo zylon-cli sync-kube-config`
## update
Update Zylon configuration
**Aliases:** sync
Usage: `sudo zylon-cli update`
## update-password
Reset the password for a user
Usage: `sudo zylon-cli update-password --help`
**Flags:**
* `-e, --email`: Account email
## upgrade
Upgrade Zylon to the latest version
Usage: `sudo zylon-cli upgrade`
# Hard delete
Source: https://docs.zylon.ai/en/v1.57/operator-manual/configuration/cron-tasks/hard-delete
Configure the retention policy used by the workspace cleanup task
The hard delete task permanently removes items after they have first been deleted in Zylon or marked inactive.
When chats, projects, files, or organizations are deleted in Zylon, they remain recoverable until the retention window expires. This cleanup configuration lets each organization align Zylon's permanent deletion behavior with its own data retention policy.
## Default configuration
By default, cleanup checks run daily at `03:00`, and items become eligible for hard delete after `14` days. If `timezone` is not set, Zylon uses the server machine's default timezone.
Stored log cleanup uses the same cleanup scheduler. It is disabled by default; when enabled, the default stored log retention threshold is `180` days.
```yaml theme={null}
zylonBackend:
scheduler:
cleanup:
enabled: true
cron: "0 3 * * *"
workspace:
enabled: true
deleteAfterDays: 14
logging:
enabled: false
deleteAfterDays: 180
```
## Configuration example
Edit `/etc/zylon/zylon-conf.yaml`, then apply the change with `sudo zylon-cli sync`.
Use a retention window that matches your company's policy. Many organizations require a value much higher than the default.
```yaml theme={null}
zylonBackend:
scheduler:
cleanup:
enabled: true
cron: "0 3 * * *"
timezone: "Europe/Madrid"
workspace:
enabled: true
deleteAfterDays: 365
logging:
enabled: true
deleteAfterDays: 180
```
`enabled` turns scheduled cleanup checks on or off. `cron` determines how often the system checks inactive items and stored logs, `timezone` optionally defines which timezone is used to interpret the cron expression, and `workspace.enabled` turns hard delete cleanup for workspace data on or off. `deleteAfterDays` is the number of days that must pass before an inactive item or a previously deleted item is permanently removed by the cron execution. `logging.enabled` turns stored log cleanup on or off, and `logging.deleteAfterDays` deletes stored log records older than that threshold. If `timezone` is omitted, the server machine's default timezone is used.
We suggest setting an [IANA timezone](#timezone-values) that matches your company's timezone.
## Accepted values
### Cron values
Cleanup uses the same 5-part cron format as sync:
```text theme={null}
minute hour day-of-month month day-of-week
```
Use values in these ranges:
| Field | Accepted values |
| - | - |
| Minute | `0-59` or `*` |
| Hour | `0-23` or `*` |
| Day of month | `1-31` or `*` |
| Month | `1-12` or `*` |
| Day of week | `0-6` or `*` |
Examples:
* `0 3 * * *` runs every day at 03:00
* `15 4 * * 0` runs every Sunday at 04:15
### Timezone values
`zylonBackend.scheduler.cleanup.timezone` is optional. If it is not set, the cleanup cron runs in the server machine's default timezone.
When you set `zylonBackend.scheduler.cleanup.timezone`, use a valid IANA timezone identifier. Common examples include:
* `UTC`
* `Europe/Madrid`
* `America/New_York`
* `America/Los_Angeles`
* `Asia/Tokyo`
* `Pacific/Auckland`
* `Africa/Johannesburg`
For a practical list of IANA timezone identifiers, see [IANA Time Zones](https://datetime.app/iana-timezones).
### Retention values
For `zylonBackend.scheduler.cleanup.deleteAfterDays`, use a positive whole number of days such as `14`, `30`, `90`, or `365`, according to your retention policy.
For `zylonBackend.scheduler.cleanup.logging.deleteAfterDays`, use a positive whole number of days. The default is `180` days, which is approximately six months.
The minimum supported value for `deleteAfterDays` is `1` day. Set this value according to your company's deletion or retention policy before enabling hard delete.
## Access before hard delete
Before the retention window expires, deleted data is not yet permanently removed. During that time, an operator can use the CLI migration and restore flow to recover organizations, projects, chats, or files.
If you need help performing that recovery, you can also contact [Customer support](/en/v1.57/customer-support-manual/zendesk-client-manual).
## Execution and failure handling
The cleanup task runs on the cron schedule and checks whether inactive items and previously deleted items have passed the `deleteAfterDays` retention window. When they have, the system flags them for hard delete and removes them from Zylon.
A cleanup run may permanently delete chats, files, projects, and organizations, together with associated cascaded data.
Per-item failures are logged. The task continues with other items, and the next scheduled run retries remaining items.
# Sync
Source: https://docs.zylon.ai/en/v1.57/operator-manual/configuration/cron-tasks/sync
Configure the scheduled integration sync task
The sync task keeps integration-backed knowledge base content up to date by checking connected external sources and updating the synced content in Zylon when source content is added, changed, or removed.
Use this task when you want content from [SharePoint](/en/v1.57/operator-manual/knowledge-base/sharepoint), [Confluence](/en/v1.57/operator-manual/knowledge-base/confluence), [File System](/en/v1.57/operator-manual/knowledge-base/file-system), [Claromentis](/en/v1.57/operator-manual/knowledge-base/claromentis), or other supported integrations to stay fresh without manual resyncs.
## Default configuration
By default, scheduled integration sync is disabled. When enabled, the default schedule is daily at `01:00`. If `timezone` is not set, Zylon uses the server machine's default timezone.
```yaml theme={null}
integration:
sync:
enabled: false
cron: "0 1 * * *"
```
## Configuration example
Edit `/etc/zylon/zylon-conf.yaml`, then apply the change with `sudo zylon-cli sync`.
```yaml theme={null}
integration:
sync:
enabled: true
cron: "0 1 * * *"
timezone: "Europe/Madrid"
```
`enabled` turns the scheduled sync on or off. `cron` defines when it runs, and `timezone` optionally defines which timezone is used to interpret that cron expression. If `timezone` is omitted, the server machine's default timezone is used.
We suggest setting an [IANA timezone](#timezone-values) that matches your company's timezone.
## Accepted cron and timezone values
### Cron values
Cron schedules use a 5-part format:
```text theme={null}
minute hour day-of-month month day-of-week
```
Use values in these ranges:
| Field | Accepted values |
| - | - |
| Minute | `0-59` or `*` |
| Hour | `0-23` or `*` |
| Day of month | `1-31` or `*` |
| Month | `1-12` or `*` |
| Day of week | `0-6` or `*` |
Examples:
* `0 3 * * *` runs every day at 03:00
* `30 2 * * 1` runs every Monday at 02:30
### Timezone values
`integration.sync.timezone` is optional. If it is not set, the sync cron runs in the server machine's default timezone.
When you set `integration.sync.timezone`, use a valid IANA timezone identifier. Common examples include:
* `UTC`
* `Europe/Madrid`
* `America/New_York`
* `America/Los_Angeles`
* `Asia/Tokyo`
* `Pacific/Auckland`
* `Africa/Johannesburg`
For a practical list of IANA timezone identifiers, see [IANA Time Zones](https://datetime.app/iana-timezones).
## Execution and failure handling
A scheduled sync run checks active integration content and may call external APIs, download content, create or remove synced knowledge base content, trigger ingestion, and emit sync completion messages.
If one sync target fails, the error is logged and the task continues with other targets. The next scheduled run tries again.
# Authentication Freshness
Source: https://docs.zylon.ai/en/v1.57/operator-manual/configuration/features/authentication-freshness
Configure authentication freshness for sensitive workspace and backoffice actions.
Authentication freshness requires users to authenticate again when their previous authentication is too old for a sensitive action. It is controlled by the `features.authChallenge` configuration block.
Authentication freshness is not applied to API requests authenticated with tokens. Token-based integrations continue to work without any changes to their existing flows.
## Enable or disable authentication freshness
Set `features.authChallenge.enabled` to `true` to enable the feature or `false` to disable it. The feature is disabled by default in the chart values.
```yaml theme={null}
features:
authChallenge:
enabled: true
```
After changing the configuration, apply it with:
```bash theme={null}
sudo zylon-cli sync
```
When the feature is disabled, the protected actions continue to enforce their normal authorization and permission checks, but they do not require a recent authentication challenge.
## Configure freshness windows
Authentication freshness is configured separately for each risk level. Values are expressed in seconds:
| Risk level | Chart key | Default | Default duration |
| - | - | -: | - |
| Low | `features.authChallenge.maxAgeSeconds.low` | `86400` | 24 hours |
| Medium | `features.authChallenge.maxAgeSeconds.medium` | `3600` | 1 hour |
| High | `features.authChallenge.maxAgeSeconds.high` | `900` | 15 minutes |
For example:
```yaml theme={null}
features:
authChallenge:
enabled: true
maxAgeSeconds:
low: "86400"
medium: "3600"
high: "900"
```
In the generated application configuration, the corresponding block is named `maxAuthAgeSeconds`:
```yaml theme={null}
features:
authChallenge:
maxAuthAgeSeconds:
low: "86400"
medium: "3600"
high: "900"
```
Use the key format appropriate to the configuration layer you are editing: `maxAgeSeconds` is the Helm chart values key, while `maxAuthAgeSeconds` is the application configuration key rendered by the chart.
## Risk levels and protected actions
The risk level determines which freshness window is used; it does not replace the user's permissions. The current actions that trigger this check are listed in [Authentication for Sensitive Actions](/en/v1.57/operator-manual/security/authentication-for-sensitive-actions).
# Audit Log
Source: https://docs.zylon.ai/en/v1.57/operator-manual/configuration/features/feat-audit
Enable Audit Log events and traces.
Audit events are emitted when the audit feature flag is enabled. Persisted audit history also requires internal log storage. Retention, syslog delivery, and HTTP delivery are configured through [Log Delivery and Storage](/en/v1.57/operator-manual/configuration/features/log-delivery-storage).
### Configuration
| Key | Default | Values | Description |
| - | - | - | - |
| `features.audit.enabled` | `true` | `true`, `false` | Enables Audit Log events and traces. |
| `logging.storage.enabled` | `true` | `true`, `false` | Enables internal structured log persistence for audit history. |
### Example
```yaml theme={null}
features:
audit:
enabled: true
logging:
storage:
enabled: true
```
Configure log retention and optional syslog or HTTP delivery in [Log Delivery and Storage](/en/v1.57/operator-manual/configuration/features/log-delivery-storage).
# Database Tool Connector
Source: https://docs.zylon.ai/en/v1.57/operator-manual/configuration/features/feat-database
**Feature in Alpha**
Show database connector tool in chats.
### Configuration
| Key | Default | Values | Description |
| - | - | - | - |
| `enabled` | `false` | `true \| false` | Show database connector tool in chats |
### Example
```yaml theme={null}
features:
database:
enabled: false
```
# Vision File Processing
Source: https://docs.zylon.ai/en/v1.57/operator-manual/configuration/features/feat-file-vision
**Available from version 1.56**
**Feature in Alpha**
**This feature requires a model with vision capabilities. See [AI Presets](/en/v1.57/operator-manual/ai-presets/presets).**
Enable vision-based file processing for documents and slides.
### Modes
| Mode | Description |
| - | - |
| `none` | Disables vision processing. Files are processed using text extraction only. |
| `lite` | Combines text and visual extraction to improve understanding of structure, images, charts, and diagrams. Designed to balance quality and efficiency. |
### Configuration
| Key | Default | Values | Description |
| - | - | - | - |
| `transformation.pptx.vision.mode` | `none` | `none \| lite` | Controls vision processing mode for PPTX files (`.pptx`). |
| `transformation.docling.vision.mode` | `none` | `none \| lite` | Controls vision processing mode for Docling-processed files (`.pdf`, `.docx`, `.xlsx`). |
### Recommendations
* Use `lite` when documents include important charts, diagrams, or images.
* Use `lite` for PPTX files when slide structure and chart interpretation matter.
Enabling `lite` increases resource consumption and document processing time.
### Example
```yaml theme={null}
transformation:
pptx:
vision:
mode: lite
docling:
vision:
mode: lite
```
# MCP Tool Connector
Source: https://docs.zylon.ai/en/v1.57/operator-manual/configuration/features/feat-mcp
**Feature in Alpha**
Show MCP connector tool in chats.
### Configuration
| Key | Default | Values | Description |
| - | - | - | - |
| `enabled` | `false` | `true \| false` | Show MCP connector tool in chats |
### Example
```yaml theme={null}
features:
mcp:
enabled: false
```
# Multimodalility capabilities
Source: https://docs.zylon.ai/en/v1.57/operator-manual/configuration/features/feat-multimodal
**Available from version 1.51**
**This feature requires your current model to have image capabilities**
**Feature in Alpha**
Extract and parse content from images if model capabilities supports it.
### Configuration
| Key | Default | Values | Description |
| - | - | - | - |
| `enabled` | `true` | `true \| false` | Store Audit Log events & traces |
### Example
```yaml theme={null}
features:
multimodal-image:
enabled: true
```
# Project Custom Instructions
Source: https://docs.zylon.ai/en/v1.57/operator-manual/configuration/features/feat-project-custom-instructions
Users can customize project instructions from the project settings dialog, as explained in [Adding custom instructions](/en/v1.57/user-manual/adding-custom-instructions).
These instructions are applied at the project level and influence how Zylon responds in chats.
### Configuration
Use the following key to control the maximum instructions length:
```yaml theme={null}
features:
maxInstructionsLength: 4000
```
### Configuration details
| Key | Default | Values | Description |
| - | - | - | - |
| `maxInstructionsLength` | `4000` | Positive integer | Maximum instructions length accepted by both the Workspace UI and the API |
# Web Extract
Source: https://docs.zylon.ai/en/v1.57/operator-manual/configuration/features/feat-webextract
**Feature in Alpha**
When given an URL, the AI has capabilities to extract and parse content.
### Configuration
| Key | Default | Values | Description |
| - | - | - | - |
| `enabled` | `false` | `true \| false` | Enable web page extraction and parsing |
| `timeout` | `15` | Positive integer | Timeout in seconds for each web page fetch |
| `poolSize` | `5` | Positive integer | Number of browser instances to keep in the pool |
| `poolIdleTimeout` | `300` | Positive integer | Seconds before an idle browser instance is terminated |
| `poolMaxPages` | `5` | Positive integer | Maximum concurrent pages per browser instance |
### Example
```yaml theme={null}
features:
webExtract:
enabled: true
timeout: 15
poolSize: 5
poolIdleTimeout: 300
poolMaxPages: 5
```
### Usage
When enabled, this feature allows Zylon to extract and parse content from web pages, enabling content analysis and data extraction capabilities.
# Web Search
Source: https://docs.zylon.ai/en/v1.57/operator-manual/configuration/features/feat-websearch
**Available from version 1.51**
**Feature in Alpha**
Enable web search capabilities in chats powered by Brave Search.
### Configuration
| Key | Default | Values | Description |
| - | - | - | - |
| `enabled` | `false` | `true \| false` | Enable web search capabilities in chats |
### Requirements
**Web Extract Required**: This feature requires [Web Extract](/en/v1.57/operator-manual/configuration/features/feat-webextract) to be enabled.
**Brave Search API Required**: You need a valid Brave Search API key to use this feature.
### How to Obtain a Brave Search API Key
1. **Visit the Brave Search API website**
* Navigate to [brave.com/search/api](https://brave.com/search/api/)
* Click on "Get Started" or "Sign Up"
2. **Create an account or sign in**
* Register with your email or sign in if you already have an account
* Access the API dashboard at [api-dashboard.search.brave.com](https://api-dashboard.search.brave.com/app/keys)
3. **Subscribe to a plan**
* Go to the **Subscriptions** tab in the left menu
* Choose a "Data for Search" plan based on your needs:
4. **Generate your API key**
* Navigate to **API Keys** in the left menu
* Click **"Add API Key"**
* Name your key (e.g., "Zylon Web Search Integration")
* Select the subscription plan to associate with the key
* Copy and save your API key securely
### Brave API Configuration
Web Search requires a Brave Search API provider configuration with the following parameters:
| Parameter | Type | Required | Description |
| - | - | - | - |
| `apiKey` | string | Yes | Your Brave Search API subscription token |
| `rateLimit` | number | Yes | Requests per second based on your subscription tier |
### Rate Limit Tiers
Based on your Brave Search API subscription tier:
* **Free AI**: `1.0` (1 query/second, up to 2,000 queries/month)
* **Base AI**: `20.0` (up to 20 queries/second, up to 20M queries/month)
* **Pro AI**: `50.0` (up to 50 queries/second, unlimited queries/month)
* **Enterprise**: Custom rate limits
### Example Configuration
```yaml theme={null}
features:
webExtract:
enabled: true
webSearch:
enabled: true
external:
brave:
apiKey: YOUR_BRAVE_API_KEY_HERE
rateLimit: 1.0
```
### Getting Started
1. Sign up for a Brave Search API key at [brave.com/search/api](https://brave.com/search/api/)
2. Configure the `apiKey` and `rateLimit` according to your subscription tier
3. Enable both `webExtract` and `webSearch` features
4. The Web Search functionality will be available in your chats
# Log Delivery and Storage
Source: https://docs.zylon.ai/en/v1.57/operator-manual/configuration/features/log-delivery-storage
Configure Zylon log storage, syslog delivery, and HTTP delivery.
## Overview
Zylon supports internal log storage and external log delivery through syslog and HTTP.
* Syslog delivery is intended for SIEM applications and log collectors that accept syslog or CEF events.
* HTTP delivery is intended for structured ingestion endpoints, cloud log destinations, and customer-managed collection pipelines.
* Delivery is asynchronous.
* With `failurePolicy: "drop"`, delivery is designed to stay off the critical request path when queues are full.
* Delivered events can be filtered by action patterns and organization IDs.
* Stored logs stay in the customer's Zylon deployment unless external log delivery through syslog or HTTP is enabled.
Configure these settings through the Zylon Helm values YAML. The chart maps values to backend runtime settings internally; customer configuration should use the YAML keys shown here.
For governance, auditability, EU AI Act traceability support, evidence preservation, and retention guidance, see [Auditability & AI Governance: Logging, Evidence, and SIEM Delivery](/en/v1.57/operator-manual/backoffice/log-delivery-storage). For manual log retrieval, see [Backoffice API: Logging](/en/v1.57/developer-manual/build-with-zylon/backoffice-api/logging).
## At a glance
| Channel | Enable with | Format options | Best for |
| - | - | - | - |
| Internal storage | `logging.storage.enabled: true` | Stored structured Zylon log records | Backoffice review and manual API retrieval |
| Syslog | `logging.delivery.syslog.enabled: true` | `rfc5424_json`, `cef` | SIEM applications, syslog collectors, and CEF collectors |
| HTTP | `logging.delivery.http.enabled: true` | `canonical_json` | HTTP collectors, ingestion gateways, and cloud log destinations |
Syslog and HTTP delivery can be enabled at the same time. When both are enabled, Zylon dispatches matching logs to both destinations. Filters, failure policy, queue, and batch settings are configured separately for each delivery method but follow the same behavior.
## Before you configure delivery
* Confirm the collector endpoint is reachable from the Zylon backend.
* Confirm host or URL and port.
* Select transport and format.
* Decide TLS certificate verification behavior.
* Configure collector-side input, index, parser, or ingestion route.
* Understand retention requirements in both Zylon and downstream systems.
* Review filters so required audit events are not excluded.
## Choose a delivery channel
| Requirement | Recommended channel |
| - | - |
| Existing SIEM or syslog collector input | Syslog |
| Collector accepts RFC 5424 style syslog messages | Syslog with `rfc5424_json` |
| Collector accepts CEF events | Syslog with `cef` |
| Custom HTTP ingestion gateway | HTTP with `canonical_json` |
| Vendor-specific pipeline transformation | HTTP with downstream mapping |
## Storage and retention
Internal log storage is controlled under `logging.storage`.
### Storage keys
| Key | Default | Values | Description |
| - | - | - | - |
| `enabled` | `true` | `true`, `false` | Enables internal structured log persistence. |
### Retention keys
Internal log cleanup is controlled by the cleanup scheduler under `zylonBackend.scheduler.cleanup`.
Scheduler settings:
| Key | Default | Values | Description |
| - | - | - | - |
| `enabled` | `false` | `true`, `false` | Enables the cleanup scheduler. |
| `cron` | `0 3 * * *` | cron expression | Cleanup schedule. Shared with hard delete cleanup. |
| `timezone` | `UTC` | time zone | Time zone used by the cleanup schedule. Shared with hard delete cleanup. If the runtime setting is omitted outside Helm, the backend uses the server JVM time zone. |
Under `logging`:
| Key | Default | Values | Description |
| - | - | - | - |
| `enabled` | `false` | `true`, `false` | Enables stored log cleanup. |
| `deleteAfterDays` | `180` | integer days | Deletes stored log records older than this threshold. |
External collectors such as SIEM platforms, syslog receivers, HTTP collectors, and data lakes have independent retention settings.
Stored log cleanup is off by default. The `180` day value applies only after both the cleanup scheduler and stored log cleanup are enabled.
Log retention cleanup uses the same cleanup cron and timezone settings as hard delete cleanup. Review [Hard delete cron configuration](/en/v1.57/operator-manual/configuration/cron-tasks/hard-delete) before changing the shared cleanup schedule.
## Syslog delivery
Syslog delivery sends formatted log records to a socket collector over TCP, TLS, or UDP.
Use `rfc5424_json` for structured syslog pipelines. Use `cef` when the collector has a native CEF input.
| Format | Description | Use when |
| - | - | - |
| `rfc5424_json` | RFC 5424 syslog with a JSON envelope in the message body. The schema value is `zylon.rfc5424_json.v1`. | You want structured syslog events for SIEM/search pipelines. |
| `cef` | Raw CEF event format. The CEF extension includes a raw structured record under `cs1`. | Your collector has a native CEF input. |
| Transport | Behavior |
| - | - |
| `tls` | Persistent TLS socket. Supports certificate verification and custom CA file. |
| `tcp` | Persistent TCP socket without TLS. |
| `udp` | Datagram delivery. One event is sent per datagram; stream framing is ignored. |
UDP is best-effort. It does not use stream framing and does not retry the current batch on write failure.
### Supported syslog matrix
Backend tests confirm both syslog formats with `tcp`, `tls`, and `udp`.
| Format | Transport | Framing | Notes |
| - | - | - | - |
| `rfc5424_json` | `tls` | `newline` or `octet_counting` | Recommended secure path for structured syslog collectors. |
| `rfc5424_json` | `tcp` | `newline` or `octet_counting` | Persistent socket path without TLS. |
| `rfc5424_json` | `udp` | Datagram | One datagram per event. |
| `cef` | `tcp` | `newline` or `octet_counting` | Raw CEF over TCP. |
| `cef` | `tls` | `newline` or `octet_counting` | Raw CEF over TLS. |
| `cef` | `udp` | Datagram | One datagram per event. |
### Syslog keys
Under `logging.delivery.syslog`:
| Key | Default | Values | Description |
| - | - | - | - |
| `enabled` | `false` | `true`, `false` | Enables syslog delivery. |
| `format` | `rfc5424_json` | `rfc5424_json`, `cef` | Syslog payload format. |
| `endpoint.host` | empty | hostname or IP | Required collector host. |
| `endpoint.port` | `6514` | valid TCP/UDP port | Collector port. |
| `endpoint.transport` | `tls` | `tls`, `tcp`, `udp` | Socket transport. |
| `endpoint.framing` | `newline` | `newline`, `octet_counting` | Stream framing for TCP/TLS. Ignored for UDP. |
Optional filter, delivery, queue, batch, and TLS settings are configured under their matching nested blocks in `logging.delivery.syslog`.
Under `filters`:
| Key | Default | Values | Description |
| - | - | - | - |
| `includeActionPatterns` | `[]` | wildcard list | If non-empty, only matching action names are delivered. |
| `excludeActionPatterns` | `[]` | wildcard list | Matching action names are excluded before include filters are evaluated. |
| `includeOrgIds` | `[]` | organization UUID list | If non-empty, only logs for matching organization IDs are delivered. |
Under `delivery`:
| Key | Default | Values | Description |
| - | - | - | - |
| `timeoutSeconds` | `10` | positive integer | Socket connect/write timeout. |
| `failurePolicy` | `drop` | `drop`, `block` | Queue behavior when the async queue is full. |
Under `delivery.reconnect`:
| Key | Default | Values | Description |
| - | - | - | - |
| `enabled` | `true` | `true`, `false` | Enables reconnect after connect or write failure. |
| `backoffSeconds` | `5` | non-negative integer | Backoff before reconnect after failure. |
Under `delivery.queue`:
| Key | Default | Values | Description |
| - | - | - | - |
| `maxEvents` | `10000` | positive integer | Async delivery queue capacity. |
Under `delivery.batch`:
| Key | Default | Values | Description |
| - | - | - | - |
| `maxEvents` | `25` | positive integer | Maximum events per batch. Forced to `1` for UDP. |
| `maxDelayMillis` | `250` | positive integer | Maximum time to wait before flushing a partial batch. |
| `drainTimeoutMillis` | `1000` | positive integer | Shutdown drain timeout for queued batch entries. |
Under `tls`:
| Key | Default | Values | Description |
| - | - | - | - |
| `verifyCertificate` | `false` | `true`, `false` | Enables TLS certificate and hostname verification. |
| `caCrt` | empty | PEM certificate data | Inline CA certificate data. If set and `caFile` is empty, the chart mounts it for the backend. |
| `caFile` | empty | readable file path | Custom CA bundle used when certificate verification is enabled. |
### Syslog full example
```yaml theme={null}
logging:
storage:
enabled: true
delivery:
syslog:
enabled: true
format: "rfc5424_json"
endpoint:
host: "syslog.example.com"
port: 6514
transport: "tls"
framing: "octet_counting"
filters:
includeActionPatterns:
- "ws.*"
- "backoffice.*"
excludeActionPatterns:
- "ws.user.enable"
includeOrgIds:
- "01985a4d-3c21-7000-8003-0e10dd81d901"
delivery:
timeoutSeconds: 10
failurePolicy: "drop"
reconnect:
enabled: true
backoffSeconds: 5
queue:
maxEvents: 10000
batch:
maxEvents: 25
maxDelayMillis: 250
drainTimeoutMillis: 1000
tls:
verifyCertificate: true
caFile: "/etc/zylon/certs/syslog-ca.pem"
```
### Syslog simplified example
```yaml theme={null}
logging:
delivery:
syslog:
enabled: true
format: "rfc5424_json"
endpoint:
host: "syslog.example.com"
port: 6514
transport: "tls"
```
## HTTP delivery
HTTP delivery sends structured JSON records to an HTTP collector. Use it for ingestion gateways, data lakes, or pipelines that transform Zylon's canonical payload downstream.
The supported HTTP format is `canonical_json`. The schema value is `zylon.canonical_json.v1`.
HTTP supports `POST`, optional bearer authentication, static headers using `Header=Value` or `Header: Value`, retries for network errors and HTTP `5xx` responses, and no retry for HTTP `4xx` client errors.
Vendor-specific transformations should happen at the collector or ingestion layer.
### HTTP keys
Under `logging.delivery.http`:
| Key | Default | Values | Description |
| - | - | - | - |
| `enabled` | `false` | `true`, `false` | Enables HTTP delivery. |
| `format` | `canonical_json` | `canonical_json` | HTTP payload format. |
| `endpoint.url` | empty | URL | Required when HTTP delivery is enabled. |
| `endpoint.method` | `POST` | `POST` | HTTP method. |
| `headers` | `[]` | YAML list | Static outbound headers. Supports `Header=Value` and `Header: Value`. |
Optional authentication, filter, delivery, queue, and batch settings are configured under their matching nested blocks in `logging.delivery.http`.
Under `auth`:
| Key | Default | Values | Description |
| - | - | - | - |
| `type` | `none` | `none`, `bearer` | Authentication mode. |
| `token` | empty | string | Required when `type` is `bearer`. Sent as `Authorization: Bearer `. |
Under `filters`:
| Key | Default | Values | Description |
| - | - | - | - |
| `includeActionPatterns` | `[]` | wildcard list | If non-empty, only matching action names are delivered. |
| `excludeActionPatterns` | `[]` | wildcard list | Matching action names are excluded before include filters are evaluated. |
| `includeOrgIds` | `[]` | organization UUID list | If non-empty, only logs for matching organization IDs are delivered. |
Under `delivery`:
| Key | Default | Values | Description |
| - | - | - | - |
| `timeoutSeconds` | `10` | positive integer | HTTP connect, read, and write timeout. |
| `failurePolicy` | `drop` | `drop`, `block` | Queue behavior when the async queue is full. |
Under `delivery.retry`:
| Key | Default | Values | Description |
| - | - | - | - |
| `enabled` | `true` | `true`, `false` | Enables HTTP retry. |
| `maxAttempts` | `3` | positive integer | Maximum request attempts when retry is enabled. |
| `backoffSeconds` | `3` | non-negative integer | Sleep between retry attempts. |
Under `delivery.queue`:
| Key | Default | Values | Description |
| - | - | - | - |
| `maxEvents` | `10000` | positive integer | Async delivery queue capacity. |
Under `delivery.batch`:
| Key | Default | Values | Description |
| - | - | - | - |
| `maxEvents` | `25` | positive integer | Maximum events per HTTP request. Multi-event batches are sent as a JSON array. |
| `maxDelayMillis` | `250` | positive integer | Maximum time to wait before flushing a partial batch. |
| `drainTimeoutMillis` | `1000` | positive integer | Shutdown drain timeout for queued batch entries. |
### HTTP full example
```yaml theme={null}
logging:
delivery:
http:
enabled: true
format: "canonical_json"
endpoint:
url: "https://collector.example.com/logs"
method: "POST"
auth:
type: "bearer"
token: "replace-me"
headers:
- "X-Collector-Token=replace-me"
- "X-Customer: default"
filters:
includeActionPatterns:
- "zylon.gateway.*"
- "ws.*"
excludeActionPatterns: []
includeOrgIds: []
delivery:
timeoutSeconds: 10
failurePolicy: "drop"
retry:
enabled: true
maxAttempts: 3
backoffSeconds: 3
queue:
maxEvents: 10000
batch:
maxEvents: 25
maxDelayMillis: 250
drainTimeoutMillis: 1000
```
### HTTP simplified example
```yaml theme={null}
logging:
delivery:
http:
enabled: true
format: "canonical_json"
endpoint:
url: "https://collector.example.com/logs"
method: "POST"
```
## Filtering delivered events
Syslog and HTTP delivery use the same filter behavior under `filters`.
| Key | Default | Values | Description |
| - | - | - | - |
| `includeActionPatterns` | `[]` | wildcard list | If non-empty, only matching action names are delivered. `*` matches any number of characters. Matching is case-sensitive and covers the full action string. |
| `excludeActionPatterns` | `[]` | wildcard list | Matching action names are excluded before include filters are evaluated. |
| `includeOrgIds` | `[]` | organization UUID list | If non-empty, only logs for matching organization IDs are delivered. Logs without `organization_id` are not delivered. |
Evaluation order:
1. Exclude action patterns.
2. Include action patterns.
3. Included organization IDs.
## Delivery behavior
The delivery pipeline is:
1. Zylon emits a structured log event.
2. Delivery filters decide whether to deliver it externally.
3. The event is normalized with severity, outcome, and actor metadata.
4. The event is formatted as syslog, CEF, or canonical JSON.
5. The formatted payload is placed on the async delivery queue.
6. The delivery worker sends the event to the configured destination.
7. Reconnect or retry behavior applies when delivery fails.
## Operational controls
Keep all Zylon backend nodes synchronized to a trusted time source such as NTP. The Helm chart sets the cleanup scheduler timezone to `UTC` by default; if the runtime setting is omitted outside Helm, the backend uses the server JVM time zone. Log records should be reviewed in UTC for cross-system forensic correlation.
Treat changes to `logging.storage`, `logging.delivery`, filters, retention, and collector destinations as auditable deployment changes. Capture approvals and diffs in GitOps, change management, Kubernetes audit logs, or the infrastructure audit system used by the customer.
Delivered payload schemas use markers such as `zylon.rfc5424_json.v1` and `zylon.canonical_json.v1`. SIEM parsers should route by schema marker and validate parser compatibility during upgrades.
## Failure policies
| Policy | Behavior | Use when |
| - | - | - |
| `drop` | Drops events when the async queue is full and avoids blocking request threads. | Recommended default for most production deployments. |
| `block` | Applies backpressure when the queue is full. | Use only when delivery completeness is more important than request latency. |
`failurePolicy: "block"` can slow requests when the delivery queue is full. Use it only after sizing queues and confirming collector availability.
Disk-backed external delivery spooling is not implemented.
## Queue and batching
| Setting | Description |
| - | - |
| `maxEvents` | Maximum events that can wait in the async delivery queue, or maximum events per delivery batch when set under `batch`. Larger queues absorb bursts but use more memory; larger batches can improve throughput but can increase delay. |
| `maxDelayMillis` | Maximum time before a partial batch is flushed. Smaller values reduce latency. |
| `drainTimeoutMillis` | Time allowed to drain queued batch entries during shutdown. |
For syslog over UDP, the `maxEvents` value under `delivery.batch` is forced to `1`, because one datagram carries one event. For HTTP, multi-event batches are delivered as a JSON array.
Queue and batching settings already have production defaults. If your HTTP destination, SIEM, or log collector does not require specific values, leave the defaults unchanged. Customize them only when your environment needs different throughput, latency, or burst handling.
## Reconnect and retry
### Syslog reconnect
TCP and TLS syslog delivery lazily opens a socket, reuses it, and retries the current batch once on a fresh connection after write failure. If retry fails, the reconnect backoff window applies.
| Setting | Description |
| - | - |
| `enabled` | Enables reconnect after socket failure. If disabled, future reconnect attempts stop after the first failure until process restart or appender reset. |
| `backoffSeconds` | Time before another connect attempt after failure. |
### HTTP retry
HTTP delivery reuses one HTTP client and retries failed requests according to retry settings.
| Setting | Description |
| - | - |
| `enabled` | Enables retry after retryable failures. |
| `maxAttempts` | Maximum attempts for one delivery. |
| `backoffSeconds` | Sleep between attempts. |
HTTP retries network exceptions and HTTP `5xx` responses. HTTP `4xx` responses are treated as client errors and are not retried.
## TLS configuration
| Setting | Description |
| - | - |
| `verifyCertificate` | Enables TLS certificate verification and hostname verification for syslog TLS. |
| `caFile` | Path to a readable CA file used to trust a private collector CA when verification is enabled. |
Local or lab deployments may disable certificate verification. Production deployments should enable certificate verification when the collector has a trusted certificate path. Use `caFile` under `tls` when the collector uses a private CA.
## Local validation
1. Enable one delivery channel.
2. Apply configuration.
3. Trigger an API action that emits a log, such as project creation or API token creation.
4. Query the collector.
5. Confirm the expected `event`, `action`, `log.id`, and actor fields appear.
6. Check backend logs for delivery warnings.
Validation queries depend on your collector. Use whichever search or inspection tool your destination provides, then confirm one of these payload markers appears:
* `zylon.rfc5424_json.v1` for RFC 5424 JSON syslog payloads.
* `CEF:0|Zylon` for CEF payloads.
* `zylon.canonical_json.v1` for HTTP payloads.
* A known action such as `ws.project.create`.
For reconnect testing, stop the collector, trigger events, restart the collector, then confirm new events arrive after the reconnect backoff.
## Troubleshooting
| Symptom | What to check |
| - | - |
| No events arrive | `enabled`, endpoint host or URL, port, collector reachability, and backend logs. |
| Syslog startup fails | Missing host, invalid port, unsupported format/transport/framing, or unreadable CA file. |
| TLS connection fails | Certificate verification, CA file, collector certificate, and hostname. |
| CEF events are not parsed | `format: "cef"`, collector input type, and port. |
| Requests slow down | `failurePolicy: "block"`, queue size, collector throughput, and backend logs. |
| Missing events during bursts | Queue size, batch settings, collector throughput, and whether `failurePolicy: "drop"` is acceptable. |
| Events do not reconnect after outage | Reconnect enabled setting, backoff setting, and backend logs. |
| HTTP delivery fails | Endpoint URL, method, bearer token, static headers, retry settings, and backend logs. |
| HTTP keeps failing without retry | Collector HTTP `4xx` responses. Fix auth, URL, headers, or collector route. |
| Retention is shorter than expected | Log cleanup settings, DB retention/backup policy, and downstream collector retention. |
## Recommended production defaults
For syslog and SIEM:
* Prefer TLS where supported.
* Prefer `rfc5424_json` for structured syslog ingestion unless the collector requires CEF.
* Use `octet_counting` or `newline` according to the collector input.
* Enable certificate verification in production where possible.
* Keep `failurePolicy: "drop"` unless strict delivery completeness is more important than request latency.
* Keep queue and batch defaults unless your destination requires different throughput, latency, or burst handling.
* Keep stored log retention at or above `180` days unless legal, security, and operations teams approve a shorter period.
For HTTP:
* Use `canonical_json`.
* Keep vendor-specific transformations at the ingestion layer.
* Use bearer authentication and static headers when required by the collector.
* Tune retry settings for the collector's availability profile.
* Confirm downstream retention in the customer-controlled collector.
# n8n
Source: https://docs.zylon.ai/en/v1.57/operator-manual/configuration/n8n
n8n support is available starting from Zylon 1.52
## n8n Integration
[n8n](https://n8n.io/) is a workflow automation tool now integrated into Zylon, enabling you to create flows by connecting different services and systems. The deployment and configuration of n8n are automatically managed by Zylon, requiring minimal user setup.
### Important Considerations
* **Version management**: Zylon manages the deployed n8n version to ensure compatibility with the rest of the system. Manual n8n updates are not available.
* **Access**: n8n is available at its own subdomain (for default: `https://n8n.your-zylon-instance.com`)
* **User management**: User management in n8n is independent from Zylon users. Users must be created and managed directly within the n8n interface.
### Configuration
To enable n8n in your environment, you only need to modify the corresponding option in the `/etc/zylon/zylon-conf.yaml` file:
```yaml theme={null}
n8n:
enabled: true # Set to false to disable n8n
host: "" # Specify a custom host if needed.
publicApi:
enabled: false # Enable n8n's public REST API
externalConnection:
enabled: false # Allow outbound connections to n8n services
license:
key: "" # n8n license key
type: "" # License type (community or enterprise)
```
n8n's public API allows you to manage workflows, executions, credentials,
and other resources programmatically through REST endpoints ([API Documentation](https://docs.n8n.io/api/))
The `license` fields only apply when `externalConnection.enabled` is set to `true` and an internet connection is available.
In Semi/Full AirGap, `externalConnection.enabled` will always be `false` regardless of the configured value.
### SSL Certificates Configuration (Optional)
This section is only necessary if you are not using Let's Encrypt certificates
If your Zylon installation uses manual SSL certificates (not Let's Encrypt), you will need to create an additional Kubernetes secret specifically for n8n.
#### Create a Secret for n8n
Once you have your certificate files ready (`tls.crt` and `tls.key`), create a secret in the Kubernetes cluster specifically for n8n:
```bash theme={null}
# Create the n8n SSL secret
sudo k0s kubectl create secret tls zylon-tls-n8n --key tls.key --cert tls.crt -n zylon
# Verify the secret was created correctly
sudo k0s kubectl describe secret zylon-tls-n8n -n zylon
```
After creating the secret, reload the configuration:
```bash theme={null}
sudo zylon-cli sync
```
Your n8n instance will now use HTTPS with the configured SSL certificates.
### External Connections
When external connections are disabled, certain n8n functionalities are automatically deactivated:
* **Community packages**: Installation of packages from the NPM registry is disabled
* **Workflow templates**: Community workflow templates are disabled
* **License activation**: Licenses are not validated and will not work in this mode
These restrictions ensure that n8n operates without external dependencies.
### Proxy Configuration
n8n uses Zylon's global proxy configuration. The system automatically manages proxy certificates and endpoints, so no additional n8n-specific configuration is required.
If your organization uses a proxy, configure it following the [proxy configuration guide](/en/v1.57/operator-manual/configuration/network/proxy).
### Troubleshooting
#### DNS
If you experience DNS resolution problems with n8n (e.g., slow or failing lookups for internal services), you may need to adjust the `dnsConfig.options.ndots` setting.
To apply custom DNS settings, add the following to your configuration:
```yaml theme={null}
n8n:
dnsConfig:
options:
- name: ndots
value: "1" # Default is 5
```
After making changes, run `sudo zylon-cli sync` to apply them.
#### Certificate rejection
If you have a custom certificate n8n may reject it. To avoid TLS verification on internal calls you can set up the following flag
```yaml theme={null}
n8n:
tlsRejectUnauthorized: 0 # Default is 1
```
After making changes, run `sudo zylon-cli sync` to apply them.
## Backup Management
n8n uses PostgreSQL as its database, which means all n8n information is automatically included in Zylon's standard database backups. For more information about backup management, see the [Zylon backup documentation](/en/v1.57/operator-manual/operations/backup).
For specific use cases involving workflow migration or transfer between environments, see the [Workflow Import and Export](#workflow-import-and-export) section.
## Apply Configuration
After modifying the configuration file, apply the changes:
```bash theme={null}
sudo zylon-cli sync
```
## Workflow Import and Export
n8n provides CLI commands that allow selective export and import of entities. These commands are especially useful for:
* **Migration from other environments**: If you want to migrate n8n information to Zylon from another existing environment
* **Selective import**: Export specific workflows from other environments and import them into Zylon without needing to migrate the entire instance
For more information about CLI commands, see the [official n8n documentation](https://docs.n8n.io/hosting/cli-commands/).
### Basic Export Commands
**Export all workflows:**
```bash theme={null}
n8n export:workflow --all --output=/home/node/.n8n/workflows.json
```
**Export a specific workflow:**
```bash theme={null}
n8n export:workflow --id=42 --output=/home/node/.n8n/workflow-42.json
```
**Export credentials:**
```bash theme={null}
n8n export:credentials --all --output=/home/node/.n8n/credentials.json
```
**Export decrypted credentials:**
```bash theme={null}
n8n export:credentials --all --output=/home/node/.n8n/credentials.json --decrypted
```
Use the `--decrypted` option when migrating between instances with different encryption keys.
**Export complete instance:**
```bash theme={null}
n8n export:entities --outputDir=./outputs --includeExecutionHistoryDataTables=true
```
### Basic Import Commands
**Import workflows:**
```bash theme={null}
n8n import:workflow --input=/home/node/.n8n/workflows.json
```
**Import a specific workflow:**
```bash theme={null}
n8n import:workflow --input=/home/node/.n8n/workflow-42.json
```
**Import credentials:**
```bash theme={null}
n8n import:credentials --input=/home/node/.n8n/credentials.json
```
**Import all instance:**
It is expected that the database is empty before the import; this can be enforced with the --truncateTables parameter.
Only works if the export database type matches the target database type. Zylon n8n uses PostgreSQL.
**Import complete instance:**
```bash theme={null}
n8n import:entities --inputDir ./outputs --truncateTables true
```
### Transfer Files from Your Local Machine
If you need to import workflows, credentials or other files located on your local machine, you must first transfer them to the n8n pod:
#### 1. Get the Persistent Volume ID
```bash theme={null}
# Get the n8n Persistent Volume ID
N8N_PV_ID=$(kubectl get pvc zylon-n8n-data -o jsonpath='{.spec.volumeName}' -n zylon)
# Build the directory path
N8N_PV_DIR="/var/zylon/data/$N8N_PV_ID"
# View the result
echo $N8N_PV_DIR
```
#### 2. Copy Files to the Volume
```bash theme={null}
# Copy file from your local machine
sudo cp /local/path/workflows.json $N8N_PV_DIR/
```
#### 3. Access the Pod and Verify the File
```bash theme={null}
kubectl exec -it deployment/zylon-n8n -n zylon -- /bin/sh
# Inside the pod, verify the file is available
ls /home/node/.n8n/
```
### Important Notes
Exported entities retain their original IDs, so importing them will overwrite existing entities with the same ID.
Export files must be located in an accessible directory within the pod, typically `/home/node/.n8n/`.
# Ports and DNS
Source: https://docs.zylon.ai/en/v1.57/operator-manual/configuration/network/ports-and-dns
These ports **must be open** in order to make Zylon work:
* 80: Default http port. Only used during SSL certification generation with [https://letsencrypt.org/](https://letsencrypt.org/). If you intend to provide your own SSL certificates this port is optional.
* 443: Default https port. Used for the rest of traffic.
Map traffic to ports 80 and 443
* Zylon Port 80 ↔ Host port 80
* Zylon Port 443 ↔ Host port 443
Additional / Temporarily open ports:
* 22: SSH port. During installation and initial setup, this port should be open so your IT team or Zylon operations team can help you get the application running. As a general security practice, you should close this port as soon as the installation is complete.
* 6443: Kubernetes API service. To help our team further debug your installation, you can also open port 6443 **temporarily**. All connections to the Kubernetes service are authenticated, having this port open does not put your data at risk. During the time the port is open it will allow Zylon Operations team to access your machine.
### DNS configuration
The following requirements are needed for Zylon to work:
* Choose a domain for Zylon, for example: `zylon.company.com.` A domain name is required for a secure connection.
* Configure DNS entries so `zylon.company.com` point to the machine that has Zylon installed
After you have installed Zylon in your environment some extra steps need to be performed to be able to access it over the internet (or VPN).
Take this points into consideration:
* The web application is running locally in the user’s web browser.
* The server is running in the machine where it was installed.
* You **MUST** configure SSL/HTTPS yourself or delegate Zylon to automatically do it for you
* Do **NOT** activate SSL redirect unless you plan to provide custom SSL certificates.
During the installation, a domain was chosen to be the entry point of Zylon. This will be used as the `host` parameter in the configuration (for example [`zylon.company.com`](http://zylon.company.com))
```yaml theme={null}
# /etc/zylon/zylon-conf.yaml
# ...
ingress:
host: "zylon.company.com"
# ...
```
### Example DNS configuration
Zylon is installed in a machine with IP `32.41.12.123` . Your DNS entry could look like the following:
```bash theme={null}
**# DNS configuration for an EC2 hosted in AWS
zylon.company.com. 1800 IN CNAME ec2-32-41-12-123.compute-1.amazonaws.com.
# Similar with an A Record, using the IP directly
zylon.company.com. 1800 IN A** 32.41.12.123
```
```bash theme={null}
**# DNS configuration for an A Record, using the IP directly
zylon.otacv.com. 1800 IN A** 32.41.12.123
```
# Proxy
Source: https://docs.zylon.ai/en/v1.57/operator-manual/configuration/network/proxy
Proxy support is available starting from Zylon 1.48 and CLI version 1.23
If your Zylon installation is running in a LAN network that requires a proxy for internet access,
follow these steps to configure the proxy settings.
There are two types of proxies:
**SSL Inspection Proxy:**
* Intercepts and inspects HTTPS traffic
* Decrypts traffic using its own SSL certificate, then re-encrypts it
* Allows deep packet inspection and content filtering
**Transparent Proxy:**
* Forwards HTTPS traffic without inspecting it
* Does not modify SSL/TLS certificates
* Acts as a simple pass-through for encrypted connections
To determine which type you have, run the following command, replacing `your-proxy-address:port` with your proxy details:
```bash theme={null}
curl -x your-proxy-address:port -v https://example.com 2>&1 | grep -A 5 "Server certificate" | grep "issuer:"
```
Look at the output:
* If you get an **SSL error**, you have an **SSL inspection proxy**
* If the command succeeds, check the `issuer` field:
* If the issuer is a public certificate authority (DigiCert, Let's Encrypt, etc.),
you have a **transparent proxy**
* If the issuer is your organization's internal CA or proxy server name,
you have an **SSL inspection proxy**
Edit `/etc/zylon/zylon-conf.yaml` based on your proxy type:
```yaml theme={null}
proxy:
enabled: true
httpProxy: "http://your-proxy-address:port"
httpsProxy: "http://your-proxy-address:port"
noProxy: "your,no,proxy,exceptions"
crt: |-
-----BEGIN CERTIFICATE-----
MIIDoTCCAomgAwIBAgIGEAHcBPNvMA0GCSqGSIb3DQEBCwUAMCgxEjAQBgNVBAMM
...
ipRF9TO2AlABfLmTR7uN8o0Opc92
-----END CERTIFICATE-----
```
To obtain your proxy CA certificate, you can try running:
```bash theme={null}
echo | openssl s_client -showcerts -connect your-proxy-address:port 2>/dev/null | openssl x509
```
Note that this may not work with all proxy providers. If it fails, contact your network administrator
for the CA certificate.
```yaml theme={null}
proxy:
enabled: true
httpProxy: "http://your-proxy-address:port"
httpsProxy: "http://your-proxy-address:port"
noProxy: "your,no,proxy,exceptions"
replicated:
privateCASecret: ~
```
Do not set the `crt` field for transparent proxies. If you require SSL inspection capabilities, you must reconfigure your proxy infrastructure for SSL inspection and then follow the instructions in the SSL Inspection Proxy tab above.
Run the sync command to apply the changes:
```bash theme={null}
sudo zylon-cli sync
```
If the cluster was running before applying the proxy settings, restart the k0s controller and
recreate the Zylon pods:
```bash theme={null}
sudo systemctl daemon-reload
sudo systemctl restart k0scontroller
# Wait a few seconds until the cluster starts again
kubectl delete pods -n zylon --all
```
# Metrics Destinations
Source: https://docs.zylon.ai/en/v1.57/operator-manual/configuration/observability/destinations
Use destinations when you want to send Zylon metrics to your own monitoring backend.
This requires:
* `observability.monitoring: true`
* a destination under `k8s-monitoring.extraDestinations`
## Supported backends
Zylon supports three backend families:
| Backend | YAML type | Typical URL |
| - | - | - |
| Prometheus | `prometheus` | `https://prometheus.example.com/api/v1/write` |
| Grafana-compatible Prometheus backend | `prometheus` | `https://.grafana.net/api/prom/push` |
| OTLP collector | `otlp` | `https://otel.example.com/v1/metrics` or `grpc://otel.example.com:4317` |
There is no separate `grafana` destination type. Grafana-compatible metrics services still use `type: prometheus`.
## Destination shape
```yaml theme={null}
k8s-monitoring:
extraDestinations:
:
type: prometheus|otlp
url:
# Define authentication settings for the destination,
# if required by your backend
auth:
type: basic|bearer
# Define the proxy to connect to the destination,
# if required by your network setup
proxyURL: http://proxy:port
# Define TLS settings for the destination,
# if your endpoint uses a private or self-signed CA
tls:
ca: |
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
```
## Destination examples
Use `type: prometheus` for a self-hosted Prometheus server with remote-write enabled:
```yaml theme={null}
k8s-monitoring:
extraDestinations:
prometheus:
type: prometheus
url: https://prometheus.example.com/api/v1/write
auth:
type: basic
username: "zylon-metrics"
password: "${PROMETHEUS_API_KEY}"
```
Prometheus must have the remote-write receiver enabled, for example by starting Prometheus with:
```bash theme={null}
--web.enable-remote-write-receiver
```
For self-signed Prometheus endpoints, pass the CA certificate so TLS verification stays enabled:
```yaml theme={null}
k8s-monitoring:
extraDestinations:
prometheus-selfsigned:
type: prometheus
url: https://prometheus.internal:9090/api/v1/write
auth:
type: basic
username: "admin"
password: "${PROMETHEUS_PASS}"
tls:
ca: |
-----BEGIN CERTIFICATE-----
MIID...
-----END CERTIFICATE-----
```
Grafana Cloud and similar backends use Prometheus remote write, so they still use `type: prometheus`:
```yaml theme={null}
k8s-monitoring:
extraDestinations:
grafana-cloud:
type: prometheus
url: https://.grafana.net/api/prom/push
auth:
type: basic
username: "your-access-policy-id"
password: "${GRAFANA_CLOUD_API_KEY}"
```
Use the exact write URL and credentials given by your provider.
Use `type: otlp` when you are sending metrics to an OpenTelemetry collector.
OTLP over HTTPS:
```yaml theme={null}
k8s-monitoring:
extraDestinations:
otlp-https:
type: otlp
url: https://otel-collector.company.com/v1/metrics
auth:
type: bearer
token: "${OTLP_BEARER_TOKEN}"
```
OTLP over gRPC:
```yaml theme={null}
k8s-monitoring:
extraDestinations:
otlp-grpc:
type: otlp
url: grpc://otel-collector.company.com:4317
auth:
type: bearer
token: "${OTLP_GRPC_TOKEN}"
```
## Multiple destinations
You can send metrics to more than one backend at the same time:
```yaml theme={null}
k8s-monitoring:
extraDestinations:
grafana-primary:
type: prometheus
url: https://prometheus-prod-XX.grafana.net/api/prom/push
auth:
type: basic
username: "primary-access-id"
password: "${GRAFANA_PRIMARY_KEY}"
internal-prometheus:
type: prometheus
url: https://prometheus.internal:9090/api/v1/write
auth:
type: basic
username: "backup"
password: "${INTERNAL_PROMETHEUS_KEY}"
tls:
ca: |
-----BEGIN CERTIFICATE-----
MIID...
-----END CERTIFICATE-----
compliance-otel:
type: otlp
url: https://compliance-otel.company.com/v1/metrics
auth:
type: bearer
token: "${COMPLIANCE_OTEL_TOKEN}"
```
# External Grafana Dashboard
Source: https://docs.zylon.ai/en/v1.57/operator-manual/configuration/observability/external-grafana-dashboard
This page is for teams that use their own Grafana instance.
Zylon provides a reference dashboard for Triton and vLLM platform metrics, but importing it is a separate Grafana task. It is not required to enable observability in Zylon.
Use it when you want an external Grafana dashboard for:
* service health
* throughput and failures
* latency analysis
* scheduler and GPU bottlenecks
## What you need first
Before this dashboard is useful, you need:
* platform metrics enabled in Zylon
* a Prometheus-compatible metrics backend with Zylon metrics in it
* a Grafana instance with a Prometheus datasource connected to that backend
See [Platform Metrics](/en/v1.57/operator-manual/configuration/observability/platform-metrics) and [Metrics Destinations](/en/v1.57/operator-manual/configuration/observability/destinations).
## Import the dashboard
Download [grafana-dashboard.json](https://raw.githubusercontent.com/zylon-ai/zylon-docs/main/snippets/grafana-dashboard.json) and import it in your Grafana instance through **Dashboards → New → Import**.
For the Grafana import flow, see the [Grafana import dashboards documentation](https://grafana.com/docs/grafana/latest/visualizations/dashboards/build-dashboards/import-dashboards/).
## What the dashboard shows
The dashboard is built from the metrics exposed on the Triton `/metrics` endpoint:
* **Triton Inference Server** metrics such as request counts, latency, queue depth, and GPU health
* **vLLM** metrics such as scheduler state, KV cache use, token throughput, and latency histograms
## Dashboard filters
| Variable | Purpose |
| - | - |
| **Datasource** | Prometheus datasource to query |
| **Environment** | Deployment or company identifier |
| **Model** | Model served by Triton |
| **GPU** | `gpu_uuid` filter for GPU-specific panels |
## Reading the dashboard
Follow this order when investigating an issue:
| Section | What it helps you answer |
| - | - |
| Overview | Is the service healthy right now? |
| Throughput & Errors | How much traffic is it handling, and are requests failing? |
| Latency | Where is time being spent? |
| Capacity & Scheduler | Is the bottleneck queueing, KV cache pressure, or batching? |
| Workload Analysis | What kind of requests are clients sending? |
| GPU Health | Is the GPU saturated or memory constrained? |
| Host Resources | Is the node itself under pressure? |
## Panels by section
### Overview
Quick health indicators for success rate, requests per second, concurrent requests, and queue depth.
![Overview and Throughput & Errors sections]()
### Throughput & Errors
Request rate, failure rate, failure reasons, batching behaviour, and queue depth over time.
![Throughput & Errors panels]()
![Failure breakdown by reason, inference count vs execution count, and pending request queue depth]()
### Latency
End-to-end latency, phase breakdown, TTFT, TPOT, and request latency percentiles.
![Avg end-to-end latency and latency waterfall]()
![Avg queue, compute, and I/O overhead; Triton and vLLM TTFT percentiles]()
![Time per output token, end-to-end latency, prefill and decode time, Triton summary quantiles]()
### Capacity & Scheduler
Scheduler state, queue time, KV cache utilisation, preemptions, and batch size.
![Capacity & Scheduler panels]()
### Workload Analysis
Token throughput, prompt length, generation length, and prefix-cache behaviour.
![Token throughput, avg tokens per request, and prompt/generation length distributions]()
![Max generation tokens, max tokens per request percentiles, and prefix cache hit rate]()
### GPU Health
GPU utilisation, memory pressure, power draw, and energy consumption.
![GPU utilization, memory, power, and energy consumption panels]()
### Host Resources
CPU, RAM, and disk availability from `node_exporter`.
![CPU usage, RAM usage, and disk availability panels]()
# How to configure observability
Source: https://docs.zylon.ai/en/v1.57/operator-manual/configuration/observability/overview
Observability helps you answer three questions:
* is Zylon healthy?
* what is it doing?
* where should its metrics go?
Zylon observability has five parts:
* **Crash reporting** tells Zylon when the platform fails, so support can diagnose the problem.
* **Usage metrics** send anonymous product telemetry to Zylon.
* **Monitoring** installs the local monitoring stack inside your cluster.
* **Platform metrics** are the actual technical metrics from Triton, vLLM, GPUs, and nodes.
* **Destinations** send those metrics to your own monitoring backend.
## Getting started
For most setups, think about observability in this order:
1. Enable `monitoring` if you want metrics at all.
2. Enable `platformMetrics` if you want Triton, vLLM, GPU, and node metrics.
3. Add `destinations` if you want to send those metrics to your own backend.
4. Keep or disable `crashReporting` and `usageMetrics` depending on whether you want Zylon telemetry.
Minimal example:
```yaml theme={null}
observability:
monitoring: true
platformMetrics:
enabled: true
```
That gives you local metrics in the in-cluster monitoring stack.
### Crash reporting
```yaml theme={null}
observability:
crashReporting: true
```
`observability.crashReporting` controls whether Zylon sends crash diagnostics to Sentry.
Enable it if you want Zylon support to have failure information when the platform breaks. Disable it if you do not want any crash diagnostics sent to Zylon.
### Usage metrics
```yaml theme={null}
observability:
usageMetrics: true
```
`observability.usageMetrics` controls whether Zylon sends anonymous product telemetry to Zylon-managed observability services.
This is product-level telemetry, not the detailed Triton or vLLM metrics you use for operating the cluster. Disable it if you do not want to send usage telemetry to Zylon.
### Monitoring
Monitoring must be enabled if you want local metrics or external metric forwarding.
```yaml theme={null}
observability:
monitoring: true
```
`observability.monitoring` installs the in-cluster monitoring stack, including Prometheus, Grafana, and `k8s-monitoring`.
This is the base for everything else related to metrics. If monitoring is disabled, you cannot inspect platform metrics locally and you cannot forward them to your own destinations.
### Platform metrics
Platform metrics require monitoring:
```yaml theme={null}
observability:
monitoring: true
platformMetrics:
enabled: true
```
`observability.platformMetrics.enabled` turns on the operational metrics generated by the inference stack.
These are the metrics you use to understand request rate, failures, latency, queue depth, scheduler pressure, GPU usage, and host health. They come from Triton, vLLM, the GPU exporter, and `node_exporter`.
For the full metric configuration, see [Platform Metrics](/en/v1.57/operator-manual/configuration/observability/platform-metrics).
### External destinations
External destinations also require monitoring:
```yaml theme={null}
observability:
monitoring: true
k8s-monitoring:
extraDestinations:
my-prometheus:
type: prometheus
url: https://prometheus.example.com/api/v1/write
```
`k8s-monitoring.extraDestinations` forwards the metrics collected in your cluster to your own monitoring backend.
Use it only when you want to send metrics somewhere outside the built-in monitoring stack, for example to Prometheus, Grafana Cloud, or an OTLP collector.
For destination setup, see [Metrics Destinations](/en/v1.57/operator-manual/configuration/observability/destinations).
If your cluster restricts outbound traffic, telemetry and external destinations may require domain or endpoint allowlisting. If you disable `usageMetrics`, Zylon's telemetry domains are not needed.
## Next pages
For the core Zylon configuration:
* [Platform Metrics](/en/v1.57/operator-manual/configuration/observability/platform-metrics): enable Triton, vLLM, GPU, and node metrics
* [Metrics Destinations](/en/v1.57/operator-manual/configuration/observability/destinations): send metrics to Prometheus, Grafana-compatible backends, or OTLP
If you use your own Grafana instance, the dashboard is a separate optional step:
* [External Grafana Dashboard](/en/v1.57/operator-manual/configuration/observability/external-grafana-dashboard): import the reference dashboard into your own Grafana instance
# Platform Metrics
Source: https://docs.zylon.ai/en/v1.57/operator-manual/configuration/observability/platform-metrics
Platform metrics are the operational metrics generated by the inference stack running in your cluster.
They include:
* **Triton metrics** such as request rate, failures, queue depth, and latency
* **vLLM metrics** such as scheduler state, KV cache pressure, and token throughput
* **GPU metrics** from the DCGM exporter
* **Node metrics** from `node_exporter`
## Before you enable them
Platform metrics require the monitoring stack:
```yaml theme={null}
observability:
monitoring: true
```
## Enable platform metrics
```yaml theme={null}
observability:
monitoring: true
platformMetrics:
enabled: true
generationIntervalMs: 2000
gpu:
enabled: true
inference:
counterLatencies: true
histogramLatencies: true
summaryLatencies: true
summaryQuantiles: ""
```
## Configuration options
| Flag | Default | What it controls |
| - | - | - |
| `platformMetrics.enabled` | `false` | Turns platform metric collection on |
| `platformMetrics.generationIntervalMs` | `2000` | Triton metric generation interval |
| `platformMetrics.gpu.enabled` | `true` | Includes GPU metrics |
| `platformMetrics.inference.counterLatencies` | `true` | Enables cumulative latency counters |
| `platformMetrics.inference.histogramLatencies` | `true` | Enables latency histograms |
| `platformMetrics.inference.summaryLatencies` | `true` | Enables sliding-window latency summaries |
| `platformMetrics.inference.summaryQuantiles` | `""` | Overrides Triton's default summary quantiles |
## What you get
### Triton
Main metric family: `nv_*`
Examples:
* `nv_inference_request_success`
* `nv_inference_request_failure`
* `nv_inference_pending_request_count`
* `nv_inference_request_duration_us`
* `nv_inference_compute_infer_duration_us`
### vLLM
Main metric families:
* `vllm_llms_v1:*`
* `vllm_embeddings_v1:*`
Examples:
* `vllm_llms_v1:num_requests_running`
* `vllm_llms_v1:kv_cache_usage_perc`
* `vllm_llms_v1:time_to_first_token_seconds_bucket`
* `vllm_llms_v1:generation_tokens_total`
### GPU
Examples:
* `nv_gpu_utilization`
* `nv_gpu_memory_used_bytes`
* `nv_gpu_power_usage`
### Node
Main metric family: `node_*`
Examples:
* `node_cpu_seconds_total`
* `node_memory_MemAvailable_bytes`
* `node_filesystem_avail_bytes`
## Next step
After platform metrics are enabled, you can either:
* inspect them in the in-cluster Grafana stack
* forward them to your own backend through [Metrics Destinations](/en/v1.57/operator-manual/configuration/observability/destinations)
* use the reference [External Grafana Dashboard](/en/v1.57/operator-manual/configuration/observability/external-grafana-dashboard)
For the complete upstream metric lists, see the [Triton metrics reference](https://docs.nvidia.com/deeplearning/triton-inference-server/user-guide/docs/user_guide/metrics.html) and the [vLLM metrics reference](https://docs.vllm.ai/en/stable/usage/metrics/).
# Configuration Overview
Source: https://docs.zylon.ai/en/v1.57/operator-manual/configuration/overview
Complete guide to configuring your Zylon instance
Configure your Zylon instance to meet your organization's specific requirements. This section covers AI models, network settings, authentication, features, and advanced configurations.
***
## Configuration Workflow
Modify `/etc/zylon/zylon-conf.yaml` with your desired settings
Review your configuration for syntax errors and compatibility
Run `sudo zylon-cli sync` to apply changes to your running instance
Check that configuration changes have taken effect as expected
***
## Core Configuration
Configure AI models based on GPU capacity and enable specialized capabilities
Connect to external data sources like SharePoint, Confluence, and file systems
Enable and configure n8n workflow automation within Zylon
Configure search languages and keyword search settings for optimal content discovery
Customize branding, logos, and appearance to match your organization
***
## Network & Connectivity
Configure required network ports and DNS settings
Set up HTTP/HTTPS proxy for restricted network environments
***
## Authentication & Security
Enable Google Single Sign-On for user authentication
Configure Microsoft Entra (Azure AD) Single Sign-On
Authenticate users against an LDAP directory or Active Directory for air-gapped and on-prem deployments
***
## Features & Capabilities
Enable or disable specific features to control what's available to your users.
Track user actions and system events for compliance and security
Configure internal log storage, syslog delivery, and HTTP delivery
Enable direct database querying from chat conversations
Configure the maximum instruction length and understand project-level chat behavior settings
Integrate Model Context Protocol tools for extended capabilities
Alpha Configure vision processing for PPTX and Docling files
Enable image processing and vision capabilities in AI models
Extract and parse content from web pages in real-time
Enable internet search capabilities within chat conversations
***
## Cron Tasks
Use these pages to understand how Zylon schedules recurring backend work for sync and hard delete cleanup.
Configure the scheduled integration sync task, including cron and timezone values
Configure the retention policy used to permanently remove soft-deleted or inactive items
***
## Advanced Settings
Configure telemetry, crash reporting, and usage metrics for monitoring
Optimize resource utilization and threading for better performance
***
# Performance tweaks
Source: https://docs.zylon.ai/en/v1.57/operator-manual/configuration/performance
## Docling
### Performance Configuration
Docling uses a worker pool architecture where workers are automatically split into two groups for quality of service:
* **Small file workers**: Process files less than 1MB and less than 100 pages
* **Large file workers**: Process files greater than or equal to 1MB or greater than or equal to 100 pages
This prevents large files from blocking the processing queue.
#### Configuration Parameters
**numWorkers**: Total number of workers (automatically split 50/50 between small and large file processing)
**numThreads**: Total threads available across all workers. Each worker receives `numThreads / numWorkers` threads.
**Constraints**
* `numWorkers >= 2` and must be even
* `numThreads >= 2`
* `numThreads` must be divisible by `numWorkers`
* Recommended: Leave at least 20-30% of cores free for system processes
**Strategy**
**High concurrency, small files** → Many workers, fewer threads per worker
* Maximizes parallel processing of multiple small documents
* Use when processing many PDFs under 100 pages
**Low concurrency, large files** → Fewer workers, more threads per worker
* Allocates more computational power per document
* Use when processing scanned books or technical manuals
### Extra Configuration
**tableMode**: Controls table extraction strategy
* `accurate`: Maximum precision, higher processing time (default)
* `fast`: Speed-optimized with good accuracy
* `none`: Disables table extraction
**doCellMatching**: Enables table cell matching for improved structure recognition. Recommended for complex tables (default: `true`)
**forceFullPageOCR**: Forces full-page OCR instead of selective regions. Use when standard extraction misses content. Significantly increases processing time (default: `false`)
### Example Configurations
The following examples consider a system with 48 CPU cores. Adjust `numWorkers` and `numThreads` based on your system's CPU count and workload characteristics.
**Use case**: Steady workload with moderate file volume and average file sizes
**What this does**: Middle ground between high throughput and heavy processing. Provides 2 workers for small files and 2 for large files with 9 threads each, balancing concurrency and processing power.
```yaml theme={null}
external:
docling:
# Performance
numWorkers: 4 # 2 for small files, 2 for large files
numThreads: 36 # 9 threads per worker, leaving 12 cores free
# Extra configuration
tableMode: "accurate"
doCellMatching: true
forceFullPageOCR: false
```
**Use case**: Processing large volumes of documents under 100 pages and under 1MB
**What this does**: Maximizes concurrent file processing with 8 workers for small files and 8 for large files. Reduces threads per worker to increase parallelism. Uses fast table extraction to optimize speed over precision.
```yaml theme={null}
external:
docling:
# Performance
numWorkers: 16 # 8 for small files, 8 for large files
numThreads: 32 # 2 threads per worker, leaving 16 cores free
# Extra configuration
tableMode: "fast" # Prioritize speed
doCellMatching: false # Disable for faster processing
forceFullPageOCR: false
```
**Use case**: Processing fewer but larger or more complex documents with detailed tables
**What this does**: Allocates more computational power per document with 8 threads per worker. Uses only 2 workers for small files and 2 for large files to focus resources on thorough processing of complex content.
```yaml theme={null}
external:
docling:
# Performance
numWorkers: 4 # 2 for small files, 2 for large files
numThreads: 32 # 8 threads per worker, leaving 16 cores free
# Extra configuration
tableMode: "accurate"
doCellMatching: true
forceFullPageOCR: false
```
**Use case**: Processing primarily scanned documents or images requiring full OCR extraction
**What this does**: Reduces worker count to allocate more threads per worker for intensive OCR processing. Enables full page OCR to extract text from scanned images. Uses fewer workers (2 for small, 2 for large) with 10 threads each to maximize processing power per document.
```yaml theme={null}
external:
docling:
# Performance
numWorkers: 4 # 2 for small files, 2 for large files
numThreads: 40 # 10 threads per worker, leaving 8 cores free
# Extra configuration
tableMode: "accurate"
doCellMatching: true
forceFullPageOCR: true # Required for scanned documents
```
# Search
Source: https://docs.zylon.ai/en/v1.57/operator-manual/configuration/search
To get a better experience during search it's recommended to enable what are the languages you plan to use in Zylon for content (Chats, documents, AI Documents), the default language is `english` but multiple languages can be enabled.
```yaml theme={null}
languages:
keywordSearch: ['en', 'es', 'de']
```
The list of available languages is the following:
| Language | ISO 639-1 Code |
| - | - |
| Arabic | ar |
| Armenian | hy |
| Basque | eu |
| Catalan | ca |
| Danish | da |
| Dutch | nl |
| English | en |
| Finnish | fi |
| French | fr |
| German | de |
| Greek | el |
| Hindi | hi |
| Hungarian | hu |
| Indonesian | id |
| Irish | ga |
| Italian | it |
| Lithuanian | lt |
| Nepali | ne |
| Norwegian | no |
| Portuguese | pt |
| Romanian | ro |
| Russian | ru |
| Serbian | sr |
| Spanish | es |
| Swedish | sv |
| Tamil | ta |
| Turkish | tr |
| Yiddish | yi |
Check if your desired language is supported by [ISO-639-1](https://localizely.com/iso-639-1-list/).
You can enable/disable languages in any moment, just change the configuration and restart Zylon
# Whitelabel
Source: https://docs.zylon.ai/en/v1.57/operator-manual/configuration/whitelabel
### Whitelabel Zylon Agent
Zylon has whitelabel support, so you can now customize the AI assistant name to match your company branding.
By default, the assistant’s name is set to **Zylon**. To change it, simply update the `assistantName` field in your configuration file with your preferred name.
**Naming Guidelines**
* Keep your agent’s name under 20 characters.
* Avoid using mixed casing (e.g., “MyAIAssistant”).
* Do not include unusual symbols, special characters, or excessive punctuation (for example, “\$uper\_Bot!”).
```
assistantName: "Daisy"
```
![Screenshot 2025-09-05 at 11.05.15.png]()
# Full-Airgap Installation
Source: https://docs.zylon.ai/en/v1.57/operator-manual/installation/airgap
Install Zylon in completely offline environments
Airgap installation enables Zylon deployment in environments with zero internet access. This process requires **two separate Linux machines**: one with internet connectivity for downloading bundles, and one offline machine for running Zylon.
**Prerequisites Checklist**:
* [ ] Clean Linux machine (Ubuntu 22/24) meeting [hardware requirements](/en/v1.57/operator-manual/installation/hardware-requirements)
* [ ] Root and SSH access to the machine
* [ ] A domain name for Zylon (e.g., zylon.company.com)
* [ ] Ability to reboot the machine when needed
* [ ] Machine has `curl` installed
- [ ] Online machine with internet access to download installation bundles
- [ ] Method to transfer files (70-100 GB) to the isolated target machine (USB drive, internal network, etc.)
- [ ] Target machine has NO internet connection
- [ ] Valid SSL certificate for your domain
- [ ] Sufficient storage on online machine and transfer media for large bundles
***
## Required Network Access
In your online machine, ensure firewall access to these domains:
**Essential Services (Mandatory):**
* `get.zylon.ai` - CLI installation
* `zylon-cli.s3.us-east-1.amazonaws.com` - CLI binaries and dependencies
* `zylon-artifacts.s3.us-east-1.amazonaws.com` - Zylon installation files and updates
These domains must be reachable from the online machine to download Zylon bundles and updates.
If direct internet access is not available, you can configure a proxy server.
Set the following environment variables before running any Zylon CLI commands:
```bash theme={null}
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"
```
**Using Self-Signed Certificates**
If your proxy uses a self-signed certificate, you must also configure the CA certificate:
```bash theme={null}
export SSL_CERT_FILE="/path/to/your/ca-cert.pem"
export REQUESTS_CA_BUNDLE="/path/to/your/ca-cert.pem"
```
**Verify Proxy Configuration**
Test connectivity through the proxy before proceeding:
```bash theme={null}
# Test HTTP connectivity
curl -v -x $HTTP_PROXY http://get.zylon.ai
# Test HTTPS connectivity (if using self-signed cert)
curl -v -x $HTTPS_PROXY --cacert $SSL_CERT_FILE https://get.zylon.ai
```
**Running Commands with sudo**
⚠️ **Important:** The `sudo` command does not preserve environment variables by default. You must use the `-E` flag to pass proxy settings to commands requiring elevated privileges:
```bash theme={null}
sudo -E zylon-cli download --airgap
```
***
## Installing Zylon
Download Zylon bundles and AI models with internet access
Move bundle files to offline machine via secure transfer method
Import and install Zylon without any internet connectivity
***
### Part A: Online Machine Setup
*Estimated time: 2 min*
Before starting the installation, validate that your machine can reach `get.zylon.ai`:
```bash theme={null}
curl -sLv get.zylon.ai -m 3 | exit 1
```
If the connection is giving errors, work with your network team to resolve them. Once connectivity is verified, you can proceed.
The Zylon CLI will speed up the time it takes to get everything ready, it will take care of installing drivers, updating Zylon and configuring the system.
To install it, SSH into the machine where you want to install Zylon and run:
```bash theme={null}
# ssh @
sudo curl -sL get.zylon.ai | sh
```
Verify the installation:
```bash theme={null}
sudo zylon-cli version
```
Root access is required for CLI operations as it manages system-level dependencies and configurations.
*Estimated time: 10min*
Zylon is configured using a YAML file located at `/etc/zylon/zylon-conf.yaml`.
**Generate Initial Configuration**
Use the CLI to generate an initial configuration file:
```bash theme={null}
sudo zylon-cli config init
```
This opens an interactive prompt to guide you through configuration options.
If for any reason you got stuck during the interactive prompt, you can skip it by adding the `-y` flag to auto-generate a default configuration:
```bash theme={null}
sudo zylon-cli config init -y
```
You will need to manually edit `/etc/zylon/zylon-conf.yaml` afterward to set your desired configuration based on the [manual configuration](#manual-configuration) section.
If you executed `sudo zylon-cli config init`, all configuration is set.
Review `/etc/zylon/zylon-conf.yaml` to confirm settings. You can know more information about which settings are required in [Manual Configuration](#manual-configuration) section.
If you need to re-run the configuration wizard, execute:
```bash theme={null}
sudo zylon-cli config init
```
Edit `/etc/zylon/zylon-conf.yaml` to adjust settings as needed.
**Define your OS distribution**
Set `node.distro` to match your Ubuntu version:
```yaml theme={null}
node:
distro: "ubuntu22" # for Ubuntu 22.04
# distro: "ubuntu24" # for Ubuntu 24.04
```
**Define your CPU architecture**
Set `node.arch` to match your hardware:
```yaml theme={null}
node:
arch: "amd64" # for Intel/AMD processors
```
**Set your hardware drivers (if applicable)**
Set `node.drivers` to `generic` (this is the only supported option):
```yaml theme={null}
node:
drivers: "generic"
```
**Configure cluster type**
Set `cluster.type` to `k0s` (this is the only supported option for single instance installations):
```yaml theme={null}
cluster:
type: "k0s"
```
**Select your release channel**
Set `channel` to `stable` (recommended for production and normal use) or `unstable` (available under request for testing):
```yaml theme={null}
channel: "stable"
```
**Add your license information**
Set `license.email` to the email address assigned to your license (provided during registration).
Set `license.id` to the license ID shared with you by the Zylon team via email:
```yaml theme={null}
license:
email: "champion@company.com"
id: "2oq..."
```
**Choose your AI preset**
Set `ai.preset` based on your available GPU memory. See [AI Presets](/en/v1.57/operator-manual/ai-presets/getting-started) for details.
```yaml theme={null}
ai:
preset: "baseline-48g"
```
**Set your company identifier**
Set `companyIdentifier` to any identifier for anonymous metrics tracking (e.g., `acme-corp`). If you have multiple installations, use different identifiers (e.g., `company` and `company-test`):
```yaml theme={null}
companyIdentifier: "your-company"
```
**Disable telemetry & crash reporting**
To disable telemetry and crash reporting, add the following section:
```yaml theme={null}
observability:
crashReporting: false
usageMetrics: false
```
**Configure network ingress**
Set `ingress.host` to the domain you've prepared for Zylon. This should be a fully qualified domain name (FQDN) that points to your server's IP address.
Examples:
* `zylon.company.com`
* `ai.acme-corp.com`
* `zylon-prod.yourcompany.io`
```yaml theme={null}
ingress:
host: "zylon.your-company.com"
enabled: true
tlsEnabled: true
```
**Configure SSL certificate generation**
If your server is accessible from the internet, Let's Encrypt will automatically generate and renew SSL certificates. Keep the default `certManagerAnnotations`:
```yaml theme={null}
ingress:
certManagerAnnotations:
cert-manager.io/cluster-issuer: "letsencrypt-prod"
```
If you're in a private network or need to use a custom certificate, see [Disable Let's Encrypt](#disable-lets-encrypt) below.
**Disable Let's Encrypt**
Edit `/etc/zylon/zylon-conf.yaml` and **remove** these lines from the `ingress` section:
```yaml theme={null}
certManagerAnnotations:
cert-manager.io/cluster-issuer: "letsencrypt-prod"
```
**Airgap Settings**
Ensure these settings are included to indicate airgap installation and operation:
```yaml theme={null}
airgap:
offlineInstall: true
offlineOperation: true
```
**Local License**
Since the offline machine cannot reach `api.replicated.com`, you need a local license. Contact Zylon support to obtain it, then add:
```yaml theme={null}
license:
email: "champion@company.com"
id: "2xo..."
type: "Zylon"
data: |-
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
Replace the `data` field with the actual license data provided by Zylon team. Please be careful with formatting and indentation.
Just copy the token that starts with `eyJ...` and ends with `...`.
**View Current Configuration**
```bash theme={null}
sudo cat /etc/zylon/zylon-conf.yaml
```
You can edit the configuration file directly using your preferred text editor (e.g., `nano`, `vim`):
```bash theme={null}
# Choose one of the following commands:
sudo nano /etc/zylon/zylon-conf.yaml
sudo vim /etc/zylon/zylon-conf.yaml
```
For detailed information about all available configuration options, see the [Configuration Guide](/en/v1.57/operator-manual/configuration/overview).
*Estimated time: 10min to 1h, depending on network speed and models.*
**Before downloading Zylon**, you must download the AI models on the online machine. The models are determined by your AI preset configuration.
Check available models and compare with your AI preset:
```bash theme={null}
sudo zylon-cli models list
```
More preset details in the [AI Presets documentation](/en/v1.57/operator-manual/ai-presets/presets).
Download the models based on your configuration:
```bash theme={null}
sudo zylon-cli models download --no-install
```
This will download the AI models that you have specified in the Wizard.
If for some reason you need to download specific models, you can do so with:
```bash theme={null}
sudo zylon-cli models list
sudo zylon-cli models download --no-install model-a model-b model-c
```
For example, for `baseline-48g` preset:
```bash theme={null}
sudo zylon-cli models download --no-install txn545/qwen3.5-35b-a3b-nvfp4 mixedbread-ai/mxbai-embed-large-v1
```
*Estimated time: 5 to 30 min, depending on models size.*
After downloading the models, export them for transfer to the offline machine:
```bash theme={null}
sudo zylon-cli models export
```
This creates a `zylon-models-.tar` file in your current directory containing all selected AI models.
The model export file can be 10-100 GB depending on which models you have downloaded.
*Estimated time: 15min to 2h, depending on network speed.*
Download the specific Zylon version you want to install:
```bash theme={null}
sudo zylon-cli list-versions
# Choose your desired version from the list
sudo zylon-cli download --airgap
```
Replace `` with your target version (e.g., `1.50.0`).
Note that we **do not use** the `--models` flag here since models were already handled in the previous steps.
*Estimated time: 15 to 60 min, depending on version.*
Export the downloaded version into an airgap bundle:
```bash theme={null}
sudo zylon-cli export
```
This creates `zylon---.tar` in your current directory. Additionally, it will generate
the commands to run on the offline machine for installation to import and install Zylon. Store these commands safely.
Export can take significant time. The resulting tar file may be 60-80GB.
**First installation only!** After initial setup, the CLI self-updates from airgap bundles.
Create a bundle with CLI tools and configuration:
```bash theme={null}
sudo tar -czf zylon-initial.tar.gz \
/usr/local/bin/zylon-cli \
/usr/local/bin/zylon-forge-cli \
/etc/zylon/zylon-conf.yaml
```
*Estimated time: 5 min*
If your Zylon instance is in a private network or VPN, you need to manually provide SSL certificates.
Prepare them for transfer:
Gather your SSL certificate files:
* `crt.pem` (Certificate + Intermediate)
* `key.pem` (Private Key)
Create a tarball for transfer:
```bash theme={null}
sudo tar -czf zylon-ssl-certs.tar.gz crt.pem key.pem
```
Transfer files to the offline machine using your preferred method (SCP, USB, external drive):
**First installation:**
* `zylon---.tar` (main bundle)
* `zylon-models-.tar` (AI models)
* `zylon-initial.tar.gz` (CLI and config)
* `zylon-ssl-certs.tar.gz` (SSL certs, if applicable)
**Subsequent updates:**
* `zylon---.tar` (main bundle)
* `zylon-models-.tar` (AI models export, if adding new models)
**SCP Example**
```bash theme={null}
scp zylon---.tar user@offline-machine:/tmp/
scp zylon-models-*.tar user@offline-machine:/tmp/
scp zylon-initial.tar.gz user@offline-machine:/tmp/
scp zylon-ssl-certs.tar.gz user@offline-machine:/tmp/
```
***
### Part B: Offline Machine Installation
*Estimated time: 2 min*
**Skip if updating an existing installation.** This is only for first-time installations.
Extract CLI tools and configuration:
```bash theme={null}
cd /tmp
sudo tar -xzf zylon-initial.tar.gz -C /
sudo chmod +x /usr/local/bin/zylon-cli /usr/local/bin/zylon-forge-cli
```
Verify installation:
```bash theme={null}
sudo zylon-cli version
cat /etc/zylon/zylon-conf.yaml
```
Future updates automatically update the CLI from airgap bundles—no manual transfer needed.
Ensure your machine meets the [hardware requirements](/en/v1.57/operator-manual/installation/hardware-requirements) for Zylon.
To validate automatically if your installation meets the minimum requirements, run:
```bash theme={null}
sudo zylon-cli preflight --fresh-system -v
```
Address any issues reported before proceeding with the installation. You will not be able to continue until all preflight checks pass.
*Estimated time: 5 to 30 min, depending on model sizes.*
**Before importing Zylon**, import the AI models that were exported on the online machine:
```bash theme={null}
cd /tmp
sudo zylon-cli models import zylon-models-.tar
sudo zylon-cli models download --offline
```
`models import` registers the model artifacts locally, and `models download --offline` installs them into the offline runtime.
Verify models were installed successfully:
```bash theme={null}
sudo zylon-cli models list --installed
```
*Estimated time: 10 to 60 min, depending on bundle size and system performance.*
Import the Zylon bundle:
```bash theme={null}
cd /tmp
sudo zylon-cli import zylon---.tar
```
This process:
* Extracts all container images
* Installs dependencies offline
* Prepares the system for installation
Import can take 30+ minutes depending on bundle size and system performance. Do not interrupt.
Verify that import completed successfully by checking installed versions:
```bash theme={null}
sudo zylon-cli list-versions --offline
```
*Estimated time: 15min to 1hour, depending on system performance.*
Install Zylon using the imported bundle:
```bash theme={null}
sudo zylon-cli install --airgap
```
The AI models have already been imported in a previous step, so no `--models` flag is needed here.
*Estimated time: 5 min*
After Zylon is installed and running, create your organization and root administrator account.
**Prepare Information**
You'll need:
* **Organization name**: Your company or team name (can be changed later)
* **Email regex**: Pattern to auto-allow users to join
* For `name@company.com` emails, use: `.*@company\.com`
* For SSO (Microsoft Entra, Google), you can use: `.*`
**Run Seed Command**
```bash theme={null}
sudo zylon-cli seed \
--org-name "My Organization" \
--email-regex ".*@yourcompany\.com"
```
The command will wait if Zylon is not fully ready.
**Running the seed command will WIPE ALL DATA.** Only run this once during the initial Zylon setup.
**Login Credentials**
After seeding, retrieve the one-time login password for the admin account:
```bash theme={null}
sudo zylon-cli admin-password
```
Then log in with:
```
Username: admin@zylon.ai
Password: [the one-time password printed above]
```
The root admin email is always `admin@zylon.ai` and cannot be changed.
After first login, you can create additional administrators and configure SSO authentication.
*Estimated time: 10 min*
If you prepared SSL certificates on the online machine, extract them now:
```bash theme={null}
cd /tmp
sudo tar -xzf zylon-ssl-certs.tar.gz -C /tmp/
ls /tmp/crt.pem /tmp/key.pem
```
If you see both files, proceed to install them as follows:
**Remove Automatic Certificate Generation**
Edit `/etc/zylon/zylon-conf.yaml` and **remove** these lines:
```yaml theme={null}
certManagerAnnotations:
cert-manager.io/cluster-issuer: "letsencrypt-prod"
```
**Prepare Certificate Files**
Kubernetes requires the certificate split into two files:
* `tls.crt` - The certificate file
* `tls.key` - The private key file
**Convert from PFX (if applicable):**
If you have a `.pfx` file, convert it:
```bash theme={null}
openssl pkcs12 -in -clcerts -nokeys -out tls.crt
openssl pkcs12 -in -nocerts -out tls.key
```
**Import Certificate into Kubernetes**
```bash theme={null}
# Remove any existing certificate
sudo k0s kubectl delete secret tls zylon-tls --ignore-not-found -n zylon
# Import your certificate
sudo k0s kubectl create secret tls zylon-tls \
--key tls.key \
--cert tls.crt \
-n zylon
# Verify creation
sudo k0s kubectl describe secret zylon-tls -n zylon
```
**Apply Changes**
Reload the Zylon configuration:
```bash theme={null}
sudo zylon-cli sync
```
**Verify**
Access your Zylon instance at `https://zylon.your-company.com` and confirm:
* The connection uses HTTPS
* The browser shows a valid certificate
* No certificate warnings appear
Certificate renewal must be done manually by repeating this process with updated certificate files.
***
## Updating Zylon
Updates in airgap environments follow a similar two-machine workflow. The process is faster than initial installation since you're only transferring changes, not the entire platform.
**Estimated Time**: 45-60 minutes total (15-20 min online machine, 25-40 min offline machine)
*Estimated time: 10 to 60 min (only if adding new models)*
**Skip this step if you're not adding new AI models.**
If you're changing AI presets, upgrading GPU requirements, or need additional models:
First, check your current and available models:
```bash theme={null}
sudo zylon-cli models list
```
Download the new models:
```bash theme={null}
sudo zylon-cli models download --no-install new-model-a new-model-b
```
Compare the available models with your AI preset requirements to determine if additional models are needed. See [AI Presets documentation](/en/v1.57/operator-manual/ai-presets/presets).
*Estimated time: 5 to 30 min (only if new models were downloaded)*
**Skip this step if you didn't add new AI models.**
Export the newly downloaded models:
```bash theme={null}
sudo zylon-cli models export
```
This creates a `zylon-models-.tar` file containing all currently downloaded models.
*Estimated time: 10 to 60 min*
Download the new Zylon version bundle:
```bash theme={null}
sudo zylon-cli download --airgap
```
Note that we **no longer use** the `--models` flag during download, as models are handled separately.
*Estimated time: 10 to 60 min*
Export an incremental update bundle:
```bash theme={null}
sudo zylon-cli export --from
```
The `--from` flag creates a differential bundle containing only changes between versions, significantly reducing bundle size and transfer time.
Differential bundles are typically 5-20 GB vs. 60-80 GB for full bundles.
Transfer the bundle file(s) using your secure method:
**If you updated models:**
```bash theme={null}
scp zylon--to---.tar user@offline-machine:/tmp/
scp zylon-models-*.tar user@offline-machine:/tmp/
```
**If no new models:**
```bash theme={null}
scp zylon--to---.tar user@offline-machine:/tmp/
```
**Alternative methods:**
* USB drive
* Internal file transfer system
* Network share (if available)
*Estimated time: 5 to 30 min (only if new models were transferred)*
**Skip this step if you didn't transfer new AI models.**
Import the new models:
```bash theme={null}
cd /tmp
sudo zylon-cli models import zylon-models-*.tar
sudo zylon-cli models download --offline
```
Verify models were installed successfully:
```bash theme={null}
sudo zylon-cli models list --installed
```
Import the update bundle:
```bash theme={null}
cd /tmp
sudo zylon-cli import zylon--to---.tar
```
The import process:
* Extracts container images for the new version
* Updates system dependencies
* Prepares upgrade artifacts
This may take 10-30 minutes. Don't interrupt the process.
Verify that import completed successfully by checking installed versions:
```bash theme={null}
sudo zylon-cli list-versions --offline
```
*Estimated time: 15 to 60 min*
Apply the update to your running Zylon instance:
```bash theme={null}
sudo zylon-cli install --airgap
```
New AI models (if any) were already imported in a previous step, so no `--models` flag is needed here.
***
## Migrating to Airgap
If you have an existing Zylon installation (online or semi-airgap) and want to migrate it to a fully airgapped environment, follow this guide. This process preserves your data, configuration, and SSL certificates while transitioning to offline operation.
**Migration differs from fresh installation:**
* Your existing configuration and data will be preserved
* SSL certificates will be migrated
* Organization and users already exist
**Migration Prerequisites:**
* [ ] Existing Zylon installation (online or semi-airgap) with access
* [ ] Online machine with internet access for downloading migration bundles
* [ ] Method to transfer files (70-100 GB) between machines
* [ ] Target airgap machine with NO internet connection
* [ ] Root and SSH access to all machines involved
***
### Part A: Extract from Existing Zylon Machine
*Estimated time: 5 min*
Copy the current Zylon configuration file:
```bash theme={null}
# On existing Zylon machine
sudo cp /etc/zylon/zylon-conf.yaml /tmp/zylon-conf-backup.yaml
```
*Estimated time: 5 min*
Extract the current SSL certificates from Kubernetes to avoid regeneration:
```bash theme={null}
# Extract certificate from Kubernetes secret
sudo k0s kubectl get secret zylon-tls -n zylon -o jsonpath='{.data.tls\.crt}' | base64 -d > /tmp/tls.crt
sudo k0s kubectl get secret zylon-tls -n zylon -o jsonpath='{.data.tls\.key}' | base64 -d > /tmp/tls.key
# Verify files were created
ls -lh /tmp/tls.crt /tmp/tls.key
```
If the certificate extraction fails, it means you're using Let's Encrypt auto-generation. In this case, you'll need to provide your own certificates or continue using Let's Encrypt on the airgap machine (not recommended for airgap environments).
Transfer the configuration and certificates to your online machine:
**SCP Example:**
```bash theme={null}
# From existing Zylon machine to online machine
scp /tmp/zylon-conf-backup.yaml user@online-machine:/tmp/
scp /tmp/tls.crt user@online-machine:/tmp/
scp /tmp/tls.key user@online-machine:/tmp/
```
**Alternative methods:**
* USB drive
* Secure internal file transfer
* Network share
***
### Part B: Prepare bundle on Online Machine
*Estimated time: 2 min*
The Zylon CLI will speed up the time it takes to get everything ready, it will take care of installing drivers, updating Zylon and configuring the system.
To install it, SSH into the machine where you want to install Zylon and run:
```bash theme={null}
# ssh @
sudo curl -sL get.zylon.ai | sh
```
Verify the installation:
```bash theme={null}
sudo zylon-cli version
```
Root access is required for CLI operations as it manages system-level dependencies and configurations.
*Estimated time: 2 min*
Place the backed-up configuration in the correct location:
```bash theme={null}
sudo mkdir -p /etc/zylon
sudo cp /tmp/zylon-conf-backup.yaml /etc/zylon/zylon-conf.yaml
```
*Estimated time: 10 min*
Run the configuration wizard to update settings for airgap deployment:
```bash theme={null}
sudo zylon-cli config init
```
The wizard will guide you through updating the following settings:
**Potential Required Changes:**
1. **Installation Type**: Change from your current type (online/semi-airgap) to **Airgap**
2. **SSL Certificates**: The wizard will prompt for certificates in text format:
* Paste the contents of `/tmp/tls.crt` when prompted for the certificate
* Paste the contents of `/tmp/tls.key` when prompted for the private key
```bash theme={null}
# Display certificate (copy this output)
cat /tmp/tls.crt
# Display private key (copy this output)
cat /tmp/tls.key
```
When pasting certificates into the wizard:
* Include the full content including `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` headers
* Maintain proper line breaks and formatting
* Do not add extra spaces or characters
3. **License Information** (if changing channel):
* License Email: Provided by Zylon team
* License ID: Provided by Zylon team
* License Data: Full license token provided by Zylon team
Ensure the license data is copied exactly as provided, preserving formatting and line breaks.
4. **Channel** (if applicable):
* Change from `stable` to `X` (or as instructed by Zylon)
5. **Review All Other Settings**: The wizard will display current values—confirm or update as needed
**Verify Updated Configuration:**
```bash theme={null}
sudo cat /etc/zylon/zylon-conf.yaml
```
Confirm that everything is set correctly for AirGap operation.
*Estimated time: 15 min to 1 hour*
Download the Zylon version bundle (without AI models, as they already exist):
```bash theme={null}
sudo zylon-cli list-versions
# Choose your target version
sudo zylon-cli download --airgap
```
We're **not** including `--models` flag because:
* Existing AI models from your current installation will be preserved
* If you need to add new models, include them with `--models=model-a,model-b`. More info in fresh installation guide below.
*Estimated time: 15 to 60 min*
Export the migration bundle:
```bash theme={null}
sudo zylon-cli export
```
This creates `zylon---.tar` in your current directory.
*Estimated time: 5 min*
Create a complete migration package with CLI tools and configuration:
```bash theme={null}
sudo tar -czf zylon-migration.tar.gz \
/usr/local/bin/zylon-cli \
/usr/local/bin/zylon-forge-cli \
/etc/zylon/zylon-conf.yaml
```
Transfer the migration package to your airgap machine:
**Files to transfer:**
* `zylon---.tar` (main bundle)
* `zylon-migration.tar.gz` (CLI and updated config)
**SCP Example:**
```bash theme={null}
scp zylon---.tar user@airgap-machine:/tmp/
scp zylon-migration.tar.gz user@airgap-machine:/tmp/
```
***
### Part C: Migrate to Airgap on Offline Machine
*Estimated time: 2 min*
Extract the CLI tools and configuration:
```bash theme={null}
cd /tmp
sudo tar -xzf zylon-migration.tar.gz -C /
sudo chmod +x /usr/local/bin/zylon-cli /usr/local/bin/zylon-forge-cli
```
Verify extraction:
```bash theme={null}
sudo zylon-cli version
cat /etc/zylon/zylon-conf.yaml
```
Should show:
```yaml theme={null}
airgap:
offlineInstall: true
offlineOperation: true
```
Ensure the airgap machine meets all requirements:
```bash theme={null}
sudo zylon-cli preflight -v
```
Address any issues before proceeding.
*Estimated time: 10 to 60 min*
Import the Zylon bundle:
```bash theme={null}
cd /tmp
sudo zylon-cli import zylon---.tar
```
This process:
* Extracts all container images
* Installs dependencies offline
* Prepares the system for installation
Import can take 30+ minutes. Do not interrupt the process.
Verify import completion:
```bash theme={null}
sudo zylon-cli list-versions --offline
```
*Estimated time: 15 min to 1 hour*
Install Zylon using the imported bundle:
```bash theme={null}
sudo zylon-cli install --airgap
```
***
## Next Steps
After completing the installation, consider the following next steps to optimize your Zylon deployment:
* [Configure AI Presets](/en/v1.57/operator-manual/ai-presets) to optimize for your hardware
* [Configure Backups](/en/v1.57/operator-manual/operations/backup) for data protection
* [Review User Manual](/en/v1.57/user-manual/quick-start-guide) to get started
# Hardware requirements
Source: https://docs.zylon.ai/en/v1.57/operator-manual/installation/hardware-requirements
Zylon only has one strict requirement regarding hardware: **it must have access to a GPU with NVIDIA CUDA capabilities and enough VRAM to run the `baseline-96g` preset tier**. In practice, that means planning for **80GB to 96GB of VRAM or more**, depending on the GPU configuration. Depending on the hardware, some AI models might be restricted, so to ensure compatibility aim for newest compatible CUDA versions (12.6+).
Our recommended specifications for the best experience are:
* Operative System: Ubuntu **SERVER** 22.04 LTS or 24.04 LTS, clean installation, without additional drivers or software installed.
* CPU: Minimum of 12 core CPU amd64 architecture (x86\_64), but 16 cores are recommended
* RAM: Minimum of 64GB, but 128GB are recommended
* Storage: Unbounded, minimum of 4TB of fast storage, but 8TB are recommended
* GPU:
* Bare metal
* Server GPU (external cooling required ⚠️)
* NVIDIA H200 (141 GB)
* NVIDIA RTX PRO 6000 Server Edition (96 GB)
* NVIDIA H100 (80 / 96 GB)
* NVIDIA A100 (80 GB)
* Workstation GPU (embedded cooling system)
* NVIDIA RTX PRO 6000 (Workstation) (96 GB)
* AWS
* g7e.2xlarge [https://instances.vantage.sh/aws/ec2/g7e.2xlarge](https://instances.vantage.sh/aws/ec2/g7e.2xlarge)
* Azure Cloud
* Choose an Azure GPU SKU that provides enough total VRAM for the `baseline-96g` preset tier (typically 80GB to 96GB total VRAM or more).
* NVv3 (Requires quantized models) [https://learn.microsoft.com/en-us/azure/virtual-machines/sizes/gpu-accelerated/nvv3-series?tabs=sizebasic](https://learn.microsoft.com/en-us/azure/virtual-machines/sizes/gpu-accelerated/nvv3-series?tabs=sizebasic)
## What GPU should I buy?
Finding the right GPU for your system can be a tricky process. For example, two GPUs with the same vRAM might not perform the same:
* H100 (server) and A100 80GB are representative options for the `baseline-96g` preset tier.
On the other hand, depending on the GPU you chose, other features that might impact AI quality will be enabled, if any of them is relevant for your uses cases factor that in for your decision:
| | A100 / H100 |
| - | - |
| Requires Workstation | ✅ |
| LLM | ✅ |
| Reranker\* | ✅ |
| Multi-model (images)\* | ✅ |
\*Currently in development/under testing — subject to change in the future.
For **on-premise bare metal environments** (the usual scenario for Zylon clients), an important factor would be your ability to properly cool the GPU installed in your machine. If you don’t want to take care of it or lack the experience, go for a desktop hardware option. But keep in mind that in case you want to run bigger models or provide service to several hundreds of users, you might need to install a rack with a couple in parallel or be forced to move to server hardware models.
Another important factor would be the investment, specially regarding the GPU. The price ranges May 5, 2025 for the aforementioned models are:
| **GPU Model** | **vRAM (GB)** | **Price (USD)** |
| - | - | - |
| NVIDIA RTX PRO 6000 (Workstation) | 96 | TBD |
| NVIDIA H100 (PCIe) | 80 | $25,000 – $30,000 |
| NVIDIA H100 (SXM) | 80 | $35,000 – $40,000 |
| NVIDIA H100 (NVL) | 96 | $40,000 - $45,000 |
| NVIDIA A100 (PCIe) | 80 | $18,000 - $20,000 |
| NVIDIA A100 (SXM) | 80 | $20,000 - $25,000 |
| NVIDIA H200 | 141 | $30,000 - $32,000 |
In any case, as a direct answer to the question of which GPU should you buy, our current baseline recommendation is a configuration that supports the **`baseline-96g` preset tier**, which in practice typically means **80GB to 96GB of total VRAM or more**.
## Reference hardware for mid-size organization
If you need to acquired your AI-capable equipment from scratch, as of July 29, 2025 please consider the following [hardware recommendation](https://pcpartpicker.com/user/pablo.zylon/saved/#view=csWVD3):
![image.png]()
This reference configuration should be adapted to meet the current GPU baseline for the **`baseline-96g` preset tier**. In practice, that means using a GPU such as the **NVIDIA RTX PRO 6000 (Workstation) (96 GB)**, an **A100 80GB**, an **H100**, or a multi-GPU setup that reaches a similar tier, together with a powerful CPU (16 cores), 128 GB of RAM, enough storage capacity to operate Zylon with margin to grow, a robust cooling solution, and a motherboard sized for the selected GPU layout.
Keep in mind that this is just a recommendation, so feel free to adapt it to your preferences while keeping similar capabilities for ideal performance. We have used Amazon as a provider considering that you can assemble all the parts together by yourself, but any provider that you usually work with should be able to get a similar hardware and assemble it for you.
## Reference hardware for big-size organization
In these scenarios, we don’t provide a reference hardware configuration until we understand the requirements not only regarding number of users, but also what kind of internal operations will be run in parallel by leveraging the platform API.
In you are in this situation, we are likely already discussing about this.
# Install Zylon (Legacy)
Source: https://docs.zylon.ai/en/v1.57/operator-manual/installation/legacy
A guide to install Zylon on a single instance
This guide only applies to Zylon 1.53.0 or earlier. For newer versions, the installation process is different and you should refer to the [main installation guide](/en/v1.57/operator-manual/installation/overview).
## Prerequisites
For a smooth sailing make sure you pass this checklist before you begin the installation:
* The target machine is clean of any other software that can interfere with it. That means no docker, no kubernetes, http servers, no Nvidia drivers, etc.
* You have root and SSH access to the machine
* The machine has stable and strong Internet connection
* You can reboot the machine if needed
* Your firewall is not blocking connections to any website.
* In case you run in a restricted environment, check the [semi-airgap instructions](/en/v1.57/operator-manual/installation/semi-airgap).
* The machine has `curl` installed
* You have a domain for Zylon ready (ex: zylon.your-company.com)
* If your instance is not open to the internet you have a valid SSL certificate for that domain, it will be needed as the last step of the installation.
Once you have fulfilled the hardware requirements and have a domain ready it is time to install Zylon!
For single instance setups Zylon it’s installed using it’s CLI `zylon-cli` on the machine where you want to run it. To start the install process make sure that:
* At install time, the machine has internet connection (After Zylon has been installed internet connection it is not a requirement)
* You have ssh access to the machine
* Firewall rules will not block the CLI to download any Zylon container images or certificate generation
## Step 1: Install the Zylon CLI
*Estimated time: 2 min*
The CLI will speed up the time it takes to get everything ready, it will take care of installing drivers, updating Zylon and generating template configuration for you.
To install it, SSH into the machine where you want to install Zylon and run
```bash theme={null}
# ssh user@zylon.company.com
sudo curl -sL get.zylon.ai | sh
```
Root access is required at multiple steps into the installation, if you wish to inspect the script simply run
```yaml theme={null}
curl -sL get.zylon.ai
```
Run `sudo zylon-cli help` to get a list of all the commands!
## Step 2: Generate a configuration file for your Zylon installation
*Estimated time: 10min*
Zylon is configured with a YAML file located at `/etc/zylon/zylon-conf.yaml`.
You can use the Zylon CLI to generate a configuration template:
```bash theme={null}
sudo zylon-cli config
```
This outputs a template that you must populate with your specific values and save to `/etc/zylon/zylon-conf.yaml`.
Note that you will need root access to edit this file.
A basic configuration file will look like this:
```yaml theme={null}
# Machine configuration, this is the only supported option
node:
distro: "ubuntu22" # or ubuntu24
arch: "x86_64"
drivers: "generic"
# Cluster type, this is the only
# supported option for single instance installations
cluster:
type: "k0s"
# unstable channel also available under request
channel: "stable"
license:
email: "champion@company.com" # The email asigned to the license
id: "2oq..." # A license id a Zylon employee shared with you via email
# AI configuration, detailed information below.
ai:
preset: "baseline-96g"
# We will use this to identify your company in our anonymous metrics
# You can set any identifier, if you have multiple installations
# make the identifier different, for example, company, and company-test
companyIdentifier: "your-company"
# Enable anonymous metrics and crash reporting
observability:
crashReporting: true
usageMetrics: true
# Your network configuration
ingress:
host: "zylon.your-company.com" # The domain you have prepared for Zylon
enabled: true
tlsEnabled: true
certManagerAnnotations:
# If you plan to open the machine to the internet, SSL certificate
# will be automatically generated using letsencrypt
# Otherwise, check the SSL documentation to import a custom certificate
cert-manager.io/cluster-issuer: "letsencrypt-prod"
```
### Configuration Parameters
Fill in each required parameter using the values that match your environment:
| Parameter | Set to... | Options |
| - | - | - |
| `node.distro` | Your OS version | `ubuntu22`, `ubuntu24` |
| `node.arch` | Your CPU architecture | `x86_64`, `arm64` |
| `node.drivers` | Your hardware type | `generic` |
| `cluster.type` | `k0s` | Only `k0s` supported |
| `channel` | `stable` | `stable` (recommended), `unstable` |
| `license.email` | Your registered email | Provided during registration |
| `license.id` | Your license key | Received from Zylon team via email |
| `ai.preset` | Your hardware capacity | [See AI Presets →](/en/v1.57/operator-manual/ai-presets/presets) |
| `companyIdentifier` | Your company name | e.g., `acme-corp` |
| `ingress.host` | Your domain | e.g., `zylon.company.com` |
| `ingress.enabled` | `true` | Must be `true` |
For detailed Zylon instance configuration, refer to the [Configuration](/en/v1.57/operator-manual/configuration/overview) page.
## Step 3: Prepare the machine
*Estimated time: 5min to 45min, depending on network speed.*
In order to install Zylon the machine needs to be ready to do so, and during this step, the drivers will be installed, an embedded kubernetes cluster, and other dependencies will be setup.
This process will take between 5 to 15 minutes, it’s normal to see the output freeze while some installers are running, simply wait until it’s done.
In slow network conditions, this process might take up to 1 hour.
```bash theme={null}
sudo zylon-cli setup
```
This is what will be installed:
* Some common packages like gcc and git
* An embedded kubernetes distribution, [k0s](https://k0sproject.io/)
* [Nvidia drivers and CUDA ](https://developer.nvidia.com/cuda-downloads)
* [Nvidia Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/index.html)
* Some tool utilities to manage the kubernetes cluster (kubectl, helm, helmfile...)
Generally, you only need to run the setup once. Running it multiple times has no effect unless an update by Zylon team adds a new dependency.
It’s highly recommended to reboot the machine after this step is completed to ensure GPU drivers are properly loaded.
**Kernel upgrades (like Ubuntu unattended upgrades) will break Nvidia drivers on every change!.**
To test if the drivers are working use `nvidia-smi` utility, it will display the status of your GPU(s) or fail if the drivers are not working:
An implicit kernel update might also happen after a restart of the machine when running in cloud providers like AWS or Azure.
Check the following page for troubleshooting: [Nvidia Drivers Troubleshooting](/en/v1.57/operator-manual/troubleshooting/nvidia-drivers)
## Step 4: Install Zylon
*Estimated time: 15min to 1hour, depending on network speed.*
This step (install / update) will make Zylon available in your machine assuming the configuration file in `/etc/zylon/zylon-conf.yaml`is correct.
```bash theme={null}
sudo zylon-cli update
```
To update Zylon to a newer version, simply run this command again. You can do so as frequently as you need.
If you modify your Zylon configuration file you will also need to run the update command again.
The initial installation of Zylon will take around 15 minutes to complete after the update command itself is completed.
This is what is happening in the background:
* Zylon images are being downloaded
* AI models are being downloaded
* GPU configuration is getting applied, several validations are running to ensure compatibility
* SSL certificate is being generated
You can watch the process running. When all pods are at 1/1 ready status you can proceed.
```bash theme={null}
watch sudo k0s kubectl get pods -n zylon
# You can also watch nvidia GPU validation process, more prone to failure
watch sudo k0s kubectl get pods -n nvidia
```
If some service gets stuck in a ContainerCrashLoopBackOff for more than one hour contact us, the installation has failed.
## Step 5: Prepare your organization
To start using Zylon you will need to create your organization in it, as well as adding a root admin that will serve as your entry point for other management tasks.
You will need:
* A name for your organization (can be changed later)
* An email regex to allow users to join automatically. If your usual work email is [`name@company.com`](mailto:name@company.com) your email regex should be `.*@company\.com` . If your access control is performed with SSO (like Microsoft Entra, or Google), you can use `.*` as your regular expression.
```bash theme={null}
sudo zylon-cli seed --org-name "My Org" --email-regex ".*@yourcompany\.com"
# At seed time, if Zylon is not ready,
# this command will wait until it’s completed.
```
**Running the seed command will WIPE ALL DATA. Only do this once during the Zylon lifecycle**
After seeding, retrieve the one-time login password for the admin account:
```bash theme={null}
sudo zylon-cli admin-password
```
The credentials to login to Zylon will be:
```bash theme={null}
user: admin@zylon.ai
password: the_one_time_password_printed_above
```
The root admin email is fixed and will always be `admin@zylon.ai` . You will need to use these credentials to login for the first time in the workspace.
## Step 6 (optional): Manually installing SSL certificates
*Estimated time: 10 minutes*
If you opted in to use Let’s Encrypt certificates you can skip this section.
In case your Zylon installation is behind a VPN / private cloud and it’s not reachable through the internet you will need to configure SSL yourself. To do that you must upload your own SSL certificates and make them available to the server where Zylon is installed.
### Configuration file
First, **REMOVE** the following lines from the configuration file `/etc/zylon/zylon-conf.yaml`
```yaml theme={null}
certManagerAnnotations:
cert-manager.io/cluster-issuer: "letsencrypt-prod"
```
Since we are using Kubernetes we need to have the private key (`*.key` ) and the certificate file in two files (`*.crt` ) to store them as a secret.
### For .pfx file (ignore otherwise)
In case you have a `.pfx` file you can get the desired files with the following commands:
```bash theme={null}
openssl pkcs12 -in -clcerts -nokeys -out tls.crt
openssl pkcs12 -in -nocerts -out tls.key
```
### Create secret a secret in the kubernetes cluster
Clear previous certificates (if any) and import the new one. Zylon will look for your certificate in the cluster with the name `zylon-tls`. Note that kubernetes requires the certificate split in two files, the `.crt` with certificate itself and `.key` with the private key.
```bash theme={null}
# Import or refresh the certificates
sudo k0s kubectl delete secret tls zylon-tls --ignore-not-found -n zylon
sudo k0s kubectl create secret tls zylon-tls --key tls.key --cert tls.crt -n zylon
# Check if it's correctly created
sudo k0s kubectl describe secret zylon-tls -n zylon
```
To reload the changes done to the configuration file, reload the configuration.
```bash theme={null}
sudo zylon-cli sync
```
Finally, go to your Zylon instance and confirm that the connection is using HTTPS.
# Online Installation
Source: https://docs.zylon.ai/en/v1.57/operator-manual/installation/online
Install Zylon with full internet access
This guide covers the standard Zylon installation for environments with full internet access. The system will automatically download all required dependencies, container images, and AI models.
**Prerequisites Checklist**:
* [ ] Clean Linux machine (Ubuntu 22/24) meeting [hardware requirements](/en/v1.57/operator-manual/installation/hardware-requirements)
* [ ] Root and SSH access to the machine
* [ ] A domain name for Zylon (e.g., zylon.company.com)
* [ ] Ability to reboot the machine when needed
* [ ] Machine has `curl` installed
- [ ] Full, unrestricted internet access on the target machine
- [ ] Firewall allows outbound connections to Docker registries and package repositories
- [ ] Either:
* [ ] Port 80 and 443 open for Let's Encrypt automatic SSL certificate generation, OR
* [ ] Valid SSL certificate ready for manual configuration
***
## Installing Zylon
*Estimated time: 2 min*
The Zylon CLI will speed up the time it takes to get everything ready, it will take care of installing drivers, updating Zylon and configuring the system.
To install it, SSH into the machine where you want to install Zylon and run:
```bash theme={null}
# ssh @
sudo curl -sL get.zylon.ai | sh
```
Verify the installation:
```bash theme={null}
sudo zylon-cli version
```
Root access is required for CLI operations as it manages system-level dependencies and configurations.
Ensure your machine meets the [hardware requirements](/en/v1.57/operator-manual/installation/hardware-requirements) for Zylon.
To validate automatically if your installation meets the minimum requirements, run:
```bash theme={null}
sudo zylon-cli preflight --network --fresh-system -v
```
Address any issues reported before proceeding with the installation. You will not be able to continue until all preflight checks pass.
Are you having issues with network connectivity? Consider moving to a [Semi-Airgap Installation](/en/v1.57/operator-manual/installation/semi-airgap) or [Airgap Installation](/en/v1.57/operator-manual/installation/airgap).
Zylon requires all checks to pass before providing installation support.
*Estimated time: 10min*
Zylon is configured using a YAML file located at `/etc/zylon/zylon-conf.yaml`.
**Generate Initial Configuration**
Use the CLI to generate an initial configuration file:
```bash theme={null}
sudo zylon-cli config init
```
This opens an interactive prompt to guide you through configuration options.
If for any reason you got stuck during the interactive prompt, you can skip it by adding the `-y` flag to auto-generate a default configuration:
```bash theme={null}
sudo zylon-cli config init -y
```
You will need to manually edit `/etc/zylon/zylon-conf.yaml` afterward to set your desired configuration based on the [manual configuration](#manual-configuration) section.
If you executed `sudo zylon-cli config init`, all configuration is set.
Review `/etc/zylon/zylon-conf.yaml` to confirm settings. You can know more information about which settings are required in [Manual Configuration](#manual-configuration) section.
If you need to re-run the configuration wizard, execute:
```bash theme={null}
sudo zylon-cli config init
```
You can
Edit `/etc/zylon/zylon-conf.yaml` to adjust settings as needed.
**Define your OS distribution**
Set `node.distro` to match your Ubuntu version:
```yaml theme={null}
node:
distro: "ubuntu22" # for Ubuntu 22.04
# distro: "ubuntu24" # for Ubuntu 24.04
```
**Define your CPU architecture**
Set `node.arch` to match your hardware:
```yaml theme={null}
node:
arch: "amd64" # for Intel/AMD processors
```
**Set your hardware drivers (if applicable)**
Set `node.drivers` to `generic` (this is the only supported option):
```yaml theme={null}
node:
drivers: "generic"
```
**Configure cluster type**
Set `cluster.type` to `k0s` (this is the only supported option for single instance installations):
```yaml theme={null}
cluster:
type: "k0s"
```
**Select your release channel**
Set `channel` to `stable` (recommended for production and normal use) or `unstable` (available under request for testing):
```yaml theme={null}
channel: "stable"
```
**Add your license information**
Set `license.email` to the email address assigned to your license (provided during registration).
Set `license.id` to the license ID shared with you by the Zylon team via email:
```yaml theme={null}
license:
email: "champion@company.com"
id: "2oq..."
```
**Choose your AI preset**
Set `ai.preset` based on your available GPU memory. See [AI Presets](/en/v1.57/operator-manual/ai-presets/getting-started) for details.
```yaml theme={null}
ai:
preset: "baseline-48g"
```
**Set your company identifier**
Set `companyIdentifier` to any identifier for anonymous metrics tracking (e.g., `acme-corp`). If you have multiple installations, use different identifiers (e.g., `company` and `company-test`):
```yaml theme={null}
companyIdentifier: "your-company"
```
**Disable telemetry & crash reporting**
To disable telemetry and crash reporting, add the following section:
```yaml theme={null}
observability:
crashReporting: false
usageMetrics: false
```
**Configure network ingress**
Set `ingress.host` to the domain you've prepared for Zylon. This should be a fully qualified domain name (FQDN) that points to your server's IP address.
Examples:
* `zylon.company.com`
* `ai.acme-corp.com`
* `zylon-prod.yourcompany.io`
```yaml theme={null}
ingress:
host: "zylon.your-company.com"
enabled: true
tlsEnabled: true
```
**Configure SSL certificate generation**
If your server is accessible from the internet, Let's Encrypt will automatically generate and renew SSL certificates. Keep the default `certManagerAnnotations`:
```yaml theme={null}
ingress:
certManagerAnnotations:
cert-manager.io/cluster-issuer: "letsencrypt-prod"
```
If you're in a private network or need to use a custom certificate, see [Disable Let's Encrypt](#disable-lets-encrypt) below.
**Disable Let's Encrypt**
Edit `/etc/zylon/zylon-conf.yaml` and **remove** these lines from the `ingress` section:
```yaml theme={null}
certManagerAnnotations:
cert-manager.io/cluster-issuer: "letsencrypt-prod"
```
**View Current Configuration**
```bash theme={null}
sudo cat /etc/zylon/zylon-conf.yaml
```
You can edit the configuration file directly using your preferred text editor (e.g., `nano`, `vim`):
```bash theme={null}
# Choose one of the following commands:
sudo nano /etc/zylon/zylon-conf.yaml
sudo vim /etc/zylon/zylon-conf.yaml
```
For detailed information about all available configuration options, see the [Configuration Guide](/en/v1.57/operator-manual/configuration/overview).
*Estimated time: 10min to 1h, depending on network speed and models.*
**Before installing Zylon**, you must download the AI models. The models are determined by your AI preset configuration.
Check available models and compare with your AI preset:
```bash theme={null}
sudo zylon-cli models list
```
More preset details in the [AI Presets documentation](/en/v1.57/operator-manual/ai-presets/presets).
Download the models based on your configuration:
```bash theme={null}
sudo zylon-cli models download
```
This will download and install the AI models that you have specified in the Wizard.
If for some reason you need to download specific models, you can do so with:
```bash theme={null}
sudo zylon-cli models list
sudo zylon-cli models download model-a model-b model-c
```
For example, for `baseline-48g` preset:
```bash theme={null}
sudo zylon-cli models download txn545/qwen3.5-35b-a3b-nvfp4 mixedbread-ai/mxbai-embed-large-v1
```
*Estimated time: 15min to 1hour, depending on system performance and network speed.*
Run the installation command with your desired version:
```bash theme={null}
sudo zylon-cli list-versions
# Choose your desired version from the list
sudo zylon-cli install
```
Replace `` with your target version (e.g., `1.50.0`).
**What Gets Installed**
The installation process handles:
* System dependencies (gcc, git, etc.)
* Kubernetes distribution ([k0s](https://k0sproject.io/))
* NVIDIA drivers and CUDA (if applicable)
* Container runtime and tools (kubectl, helm)
* Zylon container images
* SSL certificate generation (if using Let's Encrypt)
Note that AI models are **not** included in this step—they were installed in the previous step.
**Monitor Installation**
Watch the installation progress:
```bash theme={null}
# Watch Zylon pods
watch sudo k0s kubectl get pods -n zylon
# Watch GPU validation (if applicable)
watch sudo k0s kubectl get pods -n nvidia
```
Wait until all pods show `1/1` ready status.
**Reboot after installation** to ensure GPU drivers load properly.
**Kernel upgrades can break NVIDIA drivers!**
Test drivers with: `nvidia-smi`
Troubleshooting: [NVIDIA Drivers Guide](/en/v1.57/operator-manual/troubleshooting/nvidia-drivers)
If services remain in `ContainerCrashLoopBackOff` for over 1 hour, contact support with logs.
*Estimated time: 5 min*
After Zylon is installed and running, create your organization and root administrator account.
**Prepare Information**
You'll need:
* **Organization name**: Your company or team name (can be changed later)
* **Email regex**: Pattern to auto-allow users to join
* For `name@company.com` emails, use: `.*@company\.com`
* For SSO (Microsoft Entra, Google), you can use: `.*`
**Run Seed Command**
```bash theme={null}
sudo zylon-cli seed \
--org-name "My Organization" \
--email-regex ".*@yourcompany\.com"
```
The command will wait if Zylon is not fully ready.
**Running the seed command will WIPE ALL DATA.** Only run this once during the initial Zylon setup.
**Login Credentials**
After seeding, retrieve the one-time login password for the admin account:
```bash theme={null}
sudo zylon-cli admin-password
```
Then log in with:
```
Username: admin@zylon.ai
Password: [the one-time password printed above]
```
The root admin email is always `admin@zylon.ai` and cannot be changed.
After first login, you can create additional administrators and configure SSO authentication.
*Estimated time: 10 min*
**Skip this step** if using Let's Encrypt automatic certificates (default for public-facing instances).
For VPN or private cloud deployments, you need to manually install SSL certificates.
**Remove Automatic Certificate Generation**
Edit `/etc/zylon/zylon-conf.yaml` and **remove** these lines:
```yaml theme={null}
certManagerAnnotations:
cert-manager.io/cluster-issuer: "letsencrypt-prod"
```
**Prepare Certificate Files**
Kubernetes requires the certificate split into two files:
* `tls.crt` - The certificate file
* `tls.key` - The private key file
**Convert from PFX (if applicable):**
If you have a `.pfx` file, convert it:
```bash theme={null}
openssl pkcs12 -in -clcerts -nokeys -out tls.crt
openssl pkcs12 -in -nocerts -out tls.key
```
**Import Certificate into Kubernetes**
```bash theme={null}
# Remove any existing certificate
sudo k0s kubectl delete secret tls zylon-tls --ignore-not-found -n zylon
# Import your certificate
sudo k0s kubectl create secret tls zylon-tls \
--key tls.key \
--cert tls.crt \
-n zylon
# Verify creation
sudo k0s kubectl describe secret zylon-tls -n zylon
```
**Apply Changes**
Reload the Zylon configuration:
```bash theme={null}
sudo zylon-cli sync
```
**Verify**
Access your Zylon instance at `https://zylon.your-company.com` and confirm:
* The connection uses HTTPS
* The browser shows a valid certificate
* No certificate warnings appear
Certificate renewal must be done manually by repeating this process with updated certificate files.
***
## Updating Zylon
Updates follow the same process as installation:
```bash theme={null}
sudo zylon-cli list-versions
# Choose your desired version from the list
sudo zylon-cli install
```
Alternatively, you can upgrade directly to the latest version using the upgrade command:
```bash theme={null}
sudo zylon-cli upgrade
```
***
## Migrating to Online
If you have an existing Zylon installation (semi-airgap or airgap) and want to migrate it to a fully online environment,
follow this guide. This process preserves your data, and configuration, while transitioning to online operation.
**Migration differs from fresh installation:**
* Your existing configuration and data will be preserved
* Organization and users already exist
To migrate an existing Zylon installation (Semi-Airgap, or Airgap) to an Online installation, follow these steps:
1. **Ensure connectivity**: Verify that the target machine has full internet access.
2. **Update configuration**: Run `sudo zylon-cli config init` to update the configuration for online operation.
3. **Refresh configuration**: Execute `sudo zylon-cli sync` to apply the new configuration settings.
4. **Verify operation**: Confirm that all services are functioning correctly with internet access.
***
## Next Steps
After completing the installation, consider the following next steps to optimize your Zylon deployment:
* [Configure AI Presets](/en/v1.57/operator-manual/ai-presets) to optimize for your hardware
* [Configure Backups](/en/v1.57/operator-manual/operations/backup) for data protection
* [Review User Manual](/en/v1.57/user-manual/quick-start-guide) to get started
# Semi-Airgap Installation
Source: https://docs.zylon.ai/en/v1.57/operator-manual/installation/semi-airgap
Install Zylon in environments with restricted internet access
This guide covers Zylon installation for environments with limited internet access due to firewall restrictions or proxy requirements. The system requires one-time internet connectivity during installation and updates.
**Prerequisites Checklist**:
* [ ] Clean Linux machine (Ubuntu 22/24) meeting [hardware requirements](/en/v1.57/operator-manual/installation/hardware-requirements)
* [ ] Root and SSH access to the machine
* [ ] A domain name for Zylon (e.g., zylon.company.com)
* [ ] Ability to reboot the machine when needed
* [ ] Machine has `curl` installed
- [ ] Proxy server configured with credentials (if required)
- [ ] Network team has whitelisted required domains and ports (see [Required Network Access](/en/v1.57/operator-manual/installation/semi-airgap#required-network-access))
- [ ] Firewall rules allow connections through the proxy
- [ ] Valid SSL certificate for your domain (Let's Encrypt typically won't work in restricted networks)
***
## Required Network Access
Your firewall must allow access to these domains:
**Essential Services (Mandatory):**
* `get.zylon.ai` - CLI installation
* `zylon-cli.s3.us-east-1.amazonaws.com` - CLI binaries and dependencies
* `zylon-artifacts.s3.us-east-1.amazonaws.com` - Zylon installation files and updates
**Public Container Registries:**
* `quay.io` - Third-party container images
* `ghcr.io` - GitHub container registry
* `docker.io` - Docker Hub images
* `registry.k8s.io` - Kubernetes images
* `reg.kyverno.io` - Kyverno policy engine
* `nvcr.io` - NVIDIA Container Registry
Since Zylon required public open-source images, network access to original registries is required during installation and updates.
If your security policies restrict access to public container registries, consider moving to an airgap installation using [Zylon Airgap Installation Guide](/en/v1.57/operator-manual/installation/airgap).
**AI Models & Dependencies (Only applicable if you need custom AI models):**
* `huggingface.co` - AI model repository
* `xet.huggingface.co` - Hugging Face XET protocol
**License Validation (Only applicable if Replicated license is used):**
* `replicated.app` - Zylon distribution platform
* `api.replicated.com` - License validation
* `proxy.replicated.com` - Zylon container images
***
## Installing Zylon
*Estimated time: 2 min*
Before starting the installation, validate that your machine can reach `get.zylon.ai`:
```bash theme={null}
curl -sLv get.zylon.ai -m 3 | exit 1
```
If the connection is giving errors, work with your network team to resolve them. Once connectivity is verified, you can proceed.
The Zylon CLI will speed up the time it takes to get everything ready, it will take care of installing drivers, updating Zylon and configuring the system.
To install it, SSH into the machine where you want to install Zylon and run:
```bash theme={null}
# ssh @
sudo curl -sL get.zylon.ai | sh
```
Verify the installation:
```bash theme={null}
sudo zylon-cli version
```
Root access is required for CLI operations as it manages system-level dependencies and configurations.
Ensure your machine meets the [hardware requirements](/en/v1.57/operator-manual/installation/hardware-requirements) for Zylon.
To validate automatically if your installation meets the minimum requirements, run:
```bash theme={null}
sudo zylon-cli preflight --network --fresh-system -v
```
Address any issues reported before proceeding with the installation. You will not be able to continue until all preflight checks pass.
Are you having issues with network connectivity? Consider moving to an [Airgap Installation](/en/v1.57/operator-manual/installation/airgap).
Zylon requires all checks to pass before providing installation support.
*Estimated time: 10min*
Zylon is configured using a YAML file located at `/etc/zylon/zylon-conf.yaml`.
**Generate Initial Configuration**
Use the CLI to generate an initial configuration file:
```bash theme={null}
sudo zylon-cli config init
```
This opens an interactive prompt to guide you through configuration options.
If for any reason you got stuck during the interactive prompt, you can skip it by adding the `-y` flag to auto-generate a default configuration:
```bash theme={null}
sudo zylon-cli config init -y
```
You will need to manually edit `/etc/zylon/zylon-conf.yaml` afterward to set your desired configuration based on the [manual configuration](#manual-configuration) section.
If you executed `sudo zylon-cli config init`, all configuration is set.
Review `/etc/zylon/zylon-conf.yaml` to confirm settings. You can know more information about which settings are required in [Manual Configuration](#manual-configuration) section.
If you need to re-run the configuration wizard, execute:
```bash theme={null}
sudo zylon-cli config init
```
You can
Edit `/etc/zylon/zylon-conf.yaml` to adjust settings as needed.
**Define your OS distribution**
Set `node.distro` to match your Ubuntu version:
```yaml theme={null}
node:
distro: "ubuntu22" # for Ubuntu 22.04
# distro: "ubuntu24" # for Ubuntu 24.04
```
**Define your CPU architecture**
Set `node.arch` to match your hardware:
```yaml theme={null}
node:
arch: "amd64" # for Intel/AMD processors
```
**Set your hardware drivers (if applicable)**
Set `node.drivers` to `generic` (this is the only supported option):
```yaml theme={null}
node:
drivers: "generic"
```
**Configure cluster type**
Set `cluster.type` to `k0s` (this is the only supported option for single instance installations):
```yaml theme={null}
cluster:
type: "k0s"
```
**Select your release channel**
Set `channel` to `stable` (recommended for production and normal use) or `unstable` (available under request for testing):
```yaml theme={null}
channel: "stable"
```
**Add your license information**
Set `license.email` to the email address assigned to your license (provided during registration).
Set `license.id` to the license ID shared with you by the Zylon team via email:
```yaml theme={null}
license:
email: "champion@company.com"
id: "2oq..."
```
**Choose your AI preset**
Set `ai.preset` based on your available GPU memory. See [AI Presets](/en/v1.57/operator-manual/ai-presets/getting-started) for details.
```yaml theme={null}
ai:
preset: "baseline-48g"
```
**Set your company identifier**
Set `companyIdentifier` to any identifier for anonymous metrics tracking (e.g., `acme-corp`). If you have multiple installations, use different identifiers (e.g., `company` and `company-test`):
```yaml theme={null}
companyIdentifier: "your-company"
```
**Disable telemetry & crash reporting**
To disable telemetry and crash reporting, add the following section:
```yaml theme={null}
observability:
crashReporting: false
usageMetrics: false
```
**Configure network ingress**
Set `ingress.host` to the domain you've prepared for Zylon. This should be a fully qualified domain name (FQDN) that points to your server's IP address.
Examples:
* `zylon.company.com`
* `ai.acme-corp.com`
* `zylon-prod.yourcompany.io`
```yaml theme={null}
ingress:
host: "zylon.your-company.com"
enabled: true
tlsEnabled: true
```
**Configure SSL certificate generation**
If your server is accessible from the internet, Let's Encrypt will automatically generate and renew SSL certificates. Keep the default `certManagerAnnotations`:
```yaml theme={null}
ingress:
certManagerAnnotations:
cert-manager.io/cluster-issuer: "letsencrypt-prod"
```
If you're in a private network or need to use a custom certificate, see [Disable Let's Encrypt](#disable-lets-encrypt) below.
**Disable Let's Encrypt**
Edit `/etc/zylon/zylon-conf.yaml` and **remove** these lines from the `ingress` section:
```yaml theme={null}
certManagerAnnotations:
cert-manager.io/cluster-issuer: "letsencrypt-prod"
```
**Local License (If Needed)**
If `api.replicated.com` is blocked during operation, you need a local license. Contact Zylon support to obtain it, then add:
```yaml theme={null}
license:
email: "champion@company.com"
id: "2xo..."
type: "Zylon"
data: |-
[eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...]
```
Replace the `data` field with the actual license data provided by Zylon team. Please be careful with formatting and indentation.
Just copy the token that starts with `eyJ...`.
**Proxy configuration (If Needed)**
Refer to the [Proxy Configuration Guide](/en/v1.57/operator-manual/configuration/network/proxy) to set up proxy settings in your configuration.
**View Current Configuration**
```bash theme={null}
sudo cat /etc/zylon/zylon-conf.yaml
```
You can edit the configuration file directly using your preferred text editor (e.g., `nano`, `vim`):
```bash theme={null}
# Choose one of the following commands:
sudo nano /etc/zylon/zylon-conf.yaml
sudo vim /etc/zylon/zylon-conf.yaml
```
For detailed information about all available configuration options, see the [Configuration Guide](/en/v1.57/operator-manual/configuration/overview).
*Estimated time: 10min to 1h, depending on network speed and models.*
**Before installing Zylon**, you must download the AI models. The models are determined by your AI preset configuration and will be downloaded from Hugging Face domains.
Ensure your firewall allows access to:
* `huggingface.co`
* `xet.huggingface.co`
Check available models and compare with your AI preset:
```bash theme={null}
sudo zylon-cli models list
```
More preset details in the [AI Presets documentation](/en/v1.57/operator-manual/ai-presets/presets).
Download the models based on your configuration:
```bash theme={null}
sudo zylon-cli models download
```
This will download and install the AI models that you have specified in the Wizard.
If for some reason you need to download specific models, you can do so with:
```bash theme={null}
sudo zylon-cli models list
sudo zylon-cli models download model-a model-b model-c
```
For example, for `baseline-48g` preset:
```bash theme={null}
sudo zylon-cli models download txn545/qwen3.5-35b-a3b-nvfp4 mixedbread-ai/mxbai-embed-large-v1
```
*Estimated time: 15min to 1hour, depending on system performance and network speed.*
Run the installation with your desired version:
```bash theme={null}
sudo zylon-cli list-versions
# Choose your desired version from the list
sudo zylon-cli install
```
The installation process handles:
* System dependencies (gcc, git, etc.)
* Kubernetes distribution ([k0s](https://k0sproject.io/))
* NVIDIA drivers and CUDA (if applicable)
* Container runtime and tools (kubectl, helm)
* Zylon container images
* SSL certificate generation (if using Let's Encrypt)
Note that AI models are **not** included in this step—they were installed in the previous step.
**Monitor Installation**
Watch the installation progress:
```bash theme={null}
# Watch Zylon pods
watch sudo k0s kubectl get pods -n zylon
# Watch GPU validation (if applicable)
watch sudo k0s kubectl get pods -n nvidia
```
Wait until all pods show `1/1` ready status.
**Reboot after installation** to ensure GPU drivers load properly.
**Kernel upgrades can break NVIDIA drivers!**
Test drivers with: `nvidia-smi`
Troubleshooting: [NVIDIA Drivers Guide](/en/v1.57/operator-manual/troubleshooting/nvidia-drivers)
If services remain in `ContainerCrashLoopBackOff` for over 1 hour, contact support with logs.
Installation may take 15-60 minutes depending on network speed and firewall restrictions.
*Estimated time: 5 min*
After Zylon is installed and running, create your organization and root administrator account.
**Prepare Information**
You'll need:
* **Organization name**: Your company or team name (can be changed later)
* **Email regex**: Pattern to auto-allow users to join
* For `name@company.com` emails, use: `.*@company\.com`
* For SSO (Microsoft Entra, Google), you can use: `.*`
**Run Seed Command**
```bash theme={null}
sudo zylon-cli seed \
--org-name "My Organization" \
--email-regex ".*@yourcompany\.com"
```
The command will wait if Zylon is not fully ready.
**Running the seed command will WIPE ALL DATA.** Only run this once during the initial Zylon setup.
**Login Credentials**
After seeding, retrieve the one-time login password for the admin account:
```bash theme={null}
sudo zylon-cli admin-password
```
Then log in with:
```
Username: admin@zylon.ai
Password: [the one-time password printed above]
```
The root admin email is always `admin@zylon.ai` and cannot be changed.
After first login, you can create additional administrators and configure SSO authentication.
*Estimated time: 5 min*
After validate that Zylon is running correctly, you can enable offline operation. This will configure Zylon to work without internet access.
Edit `/etc/zylon/zylon-conf.yaml` and add:
```yaml theme={null}
airgap:
offlineOperation: true
```
And sync the configuration:
```bash theme={null}
sudo zylon-cli sync
```
This will disable connectivity in AI, K8s and other subsystems.
*Estimated time: 10 min*
For VPN or private network deployments, you need to manually install SSL certificates.
**Remove Automatic Certificate Generation**
Edit `/etc/zylon/zylon-conf.yaml` and **remove** these lines:
```yaml theme={null}
certManagerAnnotations:
cert-manager.io/cluster-issuer: "letsencrypt-prod"
```
**Prepare Certificate Files**
Kubernetes requires the certificate split into two files:
* `tls.crt` - The certificate file
* `tls.key` - The private key file
**Convert from PFX (if applicable):**
If you have a `.pfx` file, convert it:
```bash theme={null}
openssl pkcs12 -in -clcerts -nokeys -out tls.crt
openssl pkcs12 -in -nocerts -out tls.key
```
**Import Certificate into Kubernetes**
```bash theme={null}
# Remove any existing certificate
sudo k0s kubectl delete secret tls zylon-tls --ignore-not-found -n zylon
# Import your certificate
sudo k0s kubectl create secret tls zylon-tls \
--key tls.key \
--cert tls.crt \
-n zylon
# Verify creation
sudo k0s kubectl describe secret zylon-tls -n zylon
```
**Apply Changes**
Reload the Zylon configuration:
```bash theme={null}
sudo zylon-cli sync
```
**Verify**
Access your Zylon instance at `https://zylon.your-company.com` and confirm:
* The connection uses HTTPS
* The browser shows a valid certificate
* No certificate warnings appear
Certificate renewal must be done manually by repeating this process with updated certificate files.
***
## Updating Zylon
To update the instance, we will need to remove network restrictions temporarily on a connected machine to download update packages. Contact your network security team to whitelist the required domains during this process.
After downloading, you can reapply the restrictions.
Before you update, be sure to disable offline mode by editing `/etc/zylon/zylon-conf.yaml` and setting:
```yaml theme={null}
airgap:
offlineOperation: false
```
Validate if Zylon has connectivity again by running:
```bash theme={null}
sudo zylon-cli preflight --network -v
```
If all checks pass, proceed to download and install the update:
```bash theme={null}
sudo zylon-cli list-versions
# Choose your desired version from the list
sudo zylon-cli install
```
Alternatively, you can upgrade directly to the latest version using the upgrade command:
```bash theme={null}
sudo zylon-cli upgrade
```
When the process is complete, re-enable offline mode by setting:
```yaml theme={null}
airgap:
offlineOperation: true
```
***
## Migrating to Semi-Airgap
If you have an existing Zylon installation (online or full-airgap) and want to migrate it to a semi airgapped environment, follow this guide.
This process preserves your data, and configuration, while transitioning to offline operation.
**Migration differs from fresh installation:**
* Your existing configuration and data will be preserved
* SSL certificates will be migrated
* Organization and users already exist
To migrate an existing Zylon installation (Online, or Airgap) to an Online installation, follow these steps:
1. **Ensure connectivity**: Verify that the target machine has connectivity with below domains.
2. **Update configuration**: Run `sudo zylon-cli config init` to update the configuration for online operation. Be sure to configure as [Configure Zylon](#configure-zylon) step describes.
* Be sure to select Semi-Airgap when you run the configuration wizard.
* If you don't have connectivity with replicated domains, be sure to request a local license to Zylon support team.
4. **Disable offline mode**: Edit `/etc/zylon/zylon-conf.yaml` and set:
```yaml theme={null}
airgap:
offlineOperation: false
```
5. **Refresh configuration**: Execute `sudo zylon-cli sync` to apply the new configuration settings.
6. **Verify operation**: Confirm that all services are functioning correctly.
***
## Next Steps
After completing the installation, consider the following next steps to optimize your Zylon deployment:
* [Configure AI Presets](/en/v1.57/operator-manual/ai-presets) to optimize for your hardware
* [Configure Backups](/en/v1.57/operator-manual/operations/backup) for data protection
* [Review User Manual](/en/v1.57/user-manual/quick-start-guide) to get started
# Uninstall
Source: https://docs.zylon.ai/en/v1.57/operator-manual/installation/uninstall
If you feel like something went wrong with your installation you can uninstall Zylon easily.
Be aware that doing so will WIPE ALL YOUR DATA, including users, uploaded documents and so forth. This step cannot be reverted.
Run the following command to uninstall zylon.
```bash theme={null}
helm uninstall -n zylon zylon
```
# Airgap Your Server
Source: https://docs.zylon.ai/en/v1.57/operator-manual/instance-hardening/airgap-your-server
This guide assumes you installed Zylon
using either Ubuntu 22.04 or Ubuntu 24.04 as the base OS.
For other setups, you must install UFW (Uncomplicated Firewall)
and adapt the commands accordingly.
If due to security or compliance requirements your Zylon server must operate
in an airgapped environment (no internet access), you can do so by
configuring UFW (Uncomplicated Firewall) that comes preinstalled
in your OS.
Almost all outgoing network traffic can be blocked and most Zylon features will
continue to work as usual.
Examples of features that *won't* be available without internet access are (list might grow in the future):
* AI Web search
* MCP connections
* Database integrations that require internet access (e.g.: Google BigQuery, Snowflake, etc)
Enabling airgap mode implies from this point onwards the update process needs to
be adapted via two approaches:
* Temporarily disable the firewall, run the update, re-enable the firewall
* Move to a completely airgap install procedure as described [here](/en/v1.57/operator-manual/installation/airgap)
### Configuring UFW
After any change don't forget to enable the firewall!
```bash theme={null}
sudo ufw enable --force
```
### Logging
```bash theme={null}
# Enable logging to monitor blocked/allowed traffic
sudo ufw logging low
sudo ufw enable --force
```
> **Note:** UFW logging captures firewall activity and is required for most security compliance frameworks (SOC 2, ISO 27001, NIS2). The `low` level logs all blocked packets and policy violations — this is sufficient for audit and incident response without generating excessive noise from routine allowed traffic. Logs are written by the kernel and typically appear in one or more of the following locations depending on your system configuration:
>
> * `/var/log/ufw.log` — when `rsyslog` is active (default on Ubuntu)
> * `/var/log/syslog` — fallback or alongside `ufw.log` on some configurations
> * Accessible via `sudo journalctl -k | grep UFW` on systemd-based systems
>
> We recommend verifying which location is active on your system after enabling logging.
#### Generic rules
These are the most restrictive rules that should be applied to your Zylon server.
Generally, you shouldn't need to modify them, unless you have specific
networking requirements.
```bash theme={null}
# Allow SSH (inbound & outbound), otherwise you may lock yourself out!
sudo ufw allow ssh
sudo ufw allow out ssh
# Set default policies, allow incoming traffic, deny outgoing
# Required so the workspace remains functional while blocking
# internet access
sudo ufw default allow incoming
sudo ufw default deny outgoing
# Allow loopback traffic, for k8s and local services
sudo ufw allow in on lo
sudo ufw allow out on lo
# k8s internal communication
sudo ufw allow in from 10.0.0.0/8
sudo ufw allow out to 10.0.0.0/8
```
Additionally, it's highly recommended to allow DNS resolution through UFW; otherwise,
the optional features listed below won't work properly.
Running the following bash script will add the necessary rules from
`/etc/resolv.conf`:
```bash theme={null}
for ns in $(awk '/^nameserver/ {print $2}' /etc/resolv.conf); do
sudo ufw allow out to $ns port 53
done
```
#### Google Single Sign-On (SSO) rules
If you are using Google SSO for authentication, you need to allow
outgoing traffic to Google's OAuth servers.
The following script will fetch the current list of Google IP ranges
and add the necessary UFW rules:
```bash theme={null}
google_rules=$(
curl -s https://www.gstatic.com/ipranges/goog.json \
| jq -r '.prefixes[]
| select(.ipv4Prefix)
| "sudo ufw allow out to \(.ipv4Prefix) port 443"'
)
# And apply them
eval "$google_rules"
```
#### Microsoft Entra rules
If you are using Microsoft Entra (Azure AD) for authentication, you need to allow
outgoing traffic to Microsoft's OAuth servers.
The steps to allow Microsoft Entra are as follows:
* Download the current list of Microsoft IP ranges from [here](https://www.microsoft.com/en-us/download/details.aspx?id=56519)
* Copy the file `ServiceTags_Public_YYYYMMDD.json` to your server
* Run the following script to generate and apply the necessary UFW rules:
```bash theme={null}
# Replace ServiceTags_Public_YYYYMMDD.json with the actual filename
microsoft_rules=$(
jq -r '[.values
| map(select(.id=="AzureActiveDirectory"
or .id=="AzureActiveDirectory.ServiceEndpoint"
or .id=="AzureActiveDirectoryDomainServices"))
| .[].properties.addressPrefixes]
| flatten[]
| "sudo ufw allow out to \(.) port 443"' ServiceTags_Public_20260119.json
)
# And apply them
eval "$microsoft_rules"
```
#### Generic rules for other services:
If you are using other services that require internet access, like MCP servers,
you will need to allow outgoing traffic to those services as well by their IP addresses.
To figure out the IP addresses, you can use the `nslookup` or `dig` commands, for example:
```bash theme={null}
nslookup mcp.your-mcp-server.com
# or
dig mcp.your-mcp-server.com +short
```
# Disk Encryption
Source: https://docs.zylon.ai/en/v1.57/operator-manual/instance-hardening/disk-encryption
Encrypt your Zylon server's disk to protect data at rest on Ubuntu 24.04
This guide is written for Ubuntu 24.04. Other operating systems and distributions
may require different tools or steps — adapt accordingly.
Disk encryption ensures that data stored on your server is unreadable without the
correct passphrase, protecting it against physical theft or unauthorized hardware access.
Choose the approach that matches your situation:
* **Clean machine** — no OS installed yet. Full-disk encryption is set up during Ubuntu installation.
* **Zylon already installed** — encrypt a separate data partition without reinstalling.
***
## Option 1: Clean Machine — Full-Disk Encryption During Installation
This is the recommended approach. Ubuntu's installer can encrypt the entire disk
using LUKS (Linux Unified Key Setup) with a single passphrase.
Download the Ubuntu 24.04 Server ISO and boot your machine from it.
At the **Storage configuration** screen, select **Custom storage layout**
and then choose **Use entire disk** option.
Check **Encrypt the LVM group with LUKS**. You will be prompted to set a passphrase.
Choose a strong passphrase and store it securely — **losing it means losing access to all data**.
Finish the installer normally. On every boot, you will be prompted to enter
the passphrase before the system starts.
Once Ubuntu is running, follow the standard [Zylon installation guide](/en/v1.57/operator-manual/installation/overview).
***
## Option 2: Zylon Already Installed — Encrypt a Data Partition
If Zylon is already running, a full reinstall is disruptive. Instead, you can
create an encrypted partition for Zylon's data directory (`/var/zylon`)
using LUKS and move the data into it.
**This is a complex, high-risk operation. Data loss is possible if anything goes wrong.**
Before proceeding, back up all Zylon data and move it off the server:
```bash theme={null}
sudo zylon-cli backup
```
Copy the resulting backup file to a safe external location (S3, another machine, etc.)
and verify you can access it before continuing. Do not proceed without a verified backup.
See the [Backup guide](/en/v1.57/operator-manual/operations/backup) for details.
### Prerequisites
* A spare disk or unpartitioned space available on the server.
* `cryptsetup` and `rsync` installed:
```bash theme={null}
sudo apt install -y cryptsetup rsync
```
List available block devices to find your spare disk (e.g. `/dev/sdb`).
The `-e 7` flag excludes loop devices (snap packages) to reduce noise:
```bash theme={null}
lsblk -d -e 7
```
Replace `/dev/sdb` with your actual device. This will **erase all data on it**.
```bash theme={null}
sudo cryptsetup luksFormat /dev/sdb
```
You will be prompted to confirm (`YES`) and set a passphrase.
```bash theme={null}
sudo cryptsetup open /dev/sdb zylon-data
```
This maps the container to `/dev/mapper/zylon-data`.
```bash theme={null}
sudo mkfs.ext4 /dev/mapper/zylon-data
```
```bash theme={null}
sudo k0s stop
```
```bash theme={null}
sudo mount /dev/mapper/zylon-data /mnt/zylon-data
sudo rsync -aAX /var/zylon/ /mnt/zylon-data/
```
Verify the copy completed successfully before continuing.
```bash theme={null}
sudo mv /var/zylon /var/zylon.bak
sudo mkdir /var/zylon
sudo umount /mnt/zylon-data
sudo mount /dev/mapper/zylon-data /var/zylon
```
Add the LUKS device to `/etc/crypttab`:
```bash theme={null}
# Get the UUID of the LUKS device
sudo cryptsetup luksDump /dev/sdb | grep UUID
```
Append a line to `/etc/crypttab` (replace `YOUR_UUID` with the value above):
```
zylon-data UUID=YOUR_UUID none luks
```
Then add the mount to `/etc/fstab`:
```
/dev/mapper/zylon-data /var/zylon ext4 defaults 0 2
```
Using `none` as the key file means the passphrase will be prompted at every boot.
For headless servers, see the Ubuntu documentation on remote LUKS unlocking.
```bash theme={null}
sudo k0s start
```
Confirm everything is working, then remove the backup:
```bash theme={null}
sudo rm -rf /var/zylon.bak
```
### Automated script (alternative)
The script below performs all the steps above interactively. It will ask for
the target disk and the LUKS passphrase, then handle the rest.
Review the script before running it. It will **erase the target disk** and
stop Zylon during the migration.
Save it as `encrypt-zylon.sh` and run with `sudo bash encrypt-zylon.sh`.
```bash theme={null}
#!/usr/bin/env bash
set -eu
log() { echo "[INFO] $*"; }
warn() { echo "[WARN] $*"; }
abort() { echo "[ERROR] $*" >&2; exit 1; }
[ "$(id -u)" -eq 0 ] || abort "Run this script with sudo: sudo bash $0"
command -v cryptsetup >/dev/null || abort "cryptsetup not found. Run: apt install cryptsetup"
command -v rsync >/dev/null || abort "rsync not found. Run: apt install rsync"
lsblk -d -e 7
echo
ROOT_DISK=$(lsblk -rno PKNAME,MOUNTPOINT 2>/dev/null | awk '$2=="/" {print $1}')
if [ -n "$ROOT_DISK" ]; then
warn "Root disk (do NOT use this): /dev/$ROOT_DISK"
fi
log "Unpartitioned disks (candidates for encryption):"
lsblk -d -e 7 -rno NAME | while read -r name; do
part_count=$(lsblk "/dev/$name" -rno NAME | grep -c ".")
if [ "$part_count" -eq 1 ] && [ "$name" != "$ROOT_DISK" ]; then
size=$(lsblk -d "/dev/$name" -rno SIZE)
echo " /dev/$name $size"
fi
done
echo
read -rp "Enter the target disk device (e.g. /dev/sdb): " DEVICE
[ -b "$DEVICE" ] || abort "$DEVICE is not a valid block device."
warn "ALL DATA ON $DEVICE WILL BE ERASED. This cannot be undone."
read -rp "Type YES to confirm: " CONFIRM
[ "$CONFIRM" = "YES" ] || abort "Aborted."
MAPPER_NAME="zylon-data"
MOUNT_TMP="/mnt/zylon-data"
DATA_DIR="/var/zylon"
BACKUP_DIR="/var/zylon.bak"
log "Stopping Zylon... (if the script is interrupted from this point on, start it again manually with: sudo k0s start)"
k0s stop || true
log "Formatting $DEVICE with LUKS..."
cryptsetup luksFormat "$DEVICE"
log "Verifying LUKS formatting..."
cryptsetup isLuks "$DEVICE" || abort "LUKS formatting failed — $DEVICE is not a valid LUKS container. Aborting before any data is moved."
log "Opening encrypted container..."
cryptsetup open "$DEVICE" "$MAPPER_NAME"
[ -b "/dev/mapper/$MAPPER_NAME" ] || abort "Failed to open LUKS container — mapper device not found."
log "Creating ext4 filesystem..."
mkfs.ext4 "/dev/mapper/$MAPPER_NAME"
mkdir -p "$MOUNT_TMP"
mount "/dev/mapper/$MAPPER_NAME" "$MOUNT_TMP"
log "Copying data from $DATA_DIR to encrypted partition (this may take a while)..."
rsync -aAX "$DATA_DIR/" "$MOUNT_TMP/"
log "Swapping data directory..."
mv "$DATA_DIR" "$BACKUP_DIR"
mkdir "$DATA_DIR"
umount "$MOUNT_TMP"
mount "/dev/mapper/$MAPPER_NAME" "$DATA_DIR"
UUID=$(cryptsetup luksDump "$DEVICE" | awk '/^UUID:/ { print $2 }')
log "Updating /etc/crypttab..."
CRYPTTAB_LINE="$MAPPER_NAME UUID=$UUID none luks"
if ! grep -Fqx "$CRYPTTAB_LINE" /etc/crypttab; then
echo "$CRYPTTAB_LINE" >> /etc/crypttab
else
log "/etc/crypttab already contains the required entry; skipping."
fi
log "Updating /etc/fstab..."
FSTAB_LINE="/dev/mapper/$MAPPER_NAME $DATA_DIR ext4 defaults 0 2"
if ! grep -Fqx "$FSTAB_LINE" /etc/fstab; then
echo "$FSTAB_LINE" >> /etc/fstab
else
log "/etc/fstab already contains the required entry; skipping."
fi
log "Starting Zylon..."
k0s start
echo
log "Done. Zylon data is now on an encrypted partition."
log "Verifying..."
lsblk -o NAME,FSTYPE,MOUNTPOINT | grep -E "crypto|zylon"
echo
log "Backup at $BACKUP_DIR — remove it once everything looks good:"
echo " sudo rm -rf $BACKUP_DIR"
```
The passphrase will be prompted at every boot. For headless servers, see
the Ubuntu documentation on remote LUKS unlocking.
# Security overview
Source: https://docs.zylon.ai/en/v1.57/operator-manual/instance-hardening/overview
Guides for securing and hardening your Zylon server against unauthorized access and network exposure
Instance hardening covers the practices and configurations that reduce the attack surface of your Zylon deployment.
Apply these guides after installation to strengthen your server's security posture.
## Topics
Restrict inbound and outbound network traffic using UFW firewall rules to isolate your Zylon instance.
Encrypt your server's disk with LUKS to protect data at rest, whether setting up a clean machine or securing an existing Zylon installation.
# Claromentis
Source: https://docs.zylon.ai/en/v1.57/operator-manual/knowledge-base/claromentis
To integrate with Claromentis, you need a Claromentis intranet enabled for your company and your access credentials to **configure Zylon** to use Claromentis on the application
## Check your Claromentis domain
First, you need to verify that you can access your Claromentis intranet. Your credentials will be used later as the connection point between Zylon and Claromentis.
* Log in to your Claromentis intranet using your credentials
* Note your Claromentis domain (e.g., `https://your-company.myintranet.net` or your custom claromentis domain)
* Verify that your account has sufficient permissions to access the documents of your intranet
## Configure Zylon to use Claromentis API
With your Claromentis domain information ready from step 1,
you now need to edit the Zylon configuration file located in `/etc/zylon/zylon-conf.yaml`
```yaml theme={null}
integration:
claromentis:
enabled: true
domain: "https://your-company.myintranet.net"
```
And fill the properties with the values generated previously:
* domain → value generated on step 1.
Save and close `/etc/zylon/zylon-conf.yaml` file
Finally, execute the following command to reset Zylon and update the config
```bash theme={null}
zylon-cli sync
```
You are all set 🎉
## Troubleshooting
### I try to upload files to the knowledge base and Claromentis button is greyed out
Clear the browser cache and try again.
### When I click on `Upload files -> From Claromentis` the log in is not working
* Check that the user and password you are introducing are the same ones you use to login on Claromentis.
### I updated my credentials in Claromentis. My integration/user is stuck, and I’m not able to sync files anymore.
This fix is only for the early version of Zylon which it doesn’t have the integrations screen. If your Zylon
instance has a screen where to manage the user integrations, please use this screen instead of this guide.
**What we need is the `id` of the integration and the `zln_s` auth cookie.**
1. Go to your zylon instance and log in with the user you want to update
2. Open the developer tools of the browser (right click => inspect)
3. On the new sidebar open, go the `Application` tab,
select `Cookies` and select the domain of your zylon instance, then copy the value of the cookie `zln_s` and save it for later
4. Now, we have the auth token, let's find the `id` of the integration
5. Inside the zylon app, open the `Network` tab,
and select `Fetch/XHR` and filter by the word `integrations`
6. Now, inside the zylon app, navigate to the project you
integrated and go to the knowledge base, you will see in the network tab one request, click on it to see the details, and you'll be able to see a list of integrations, search for the `type: "Claromentis"`, now you can see the `id`
7. Next, open a terminal with cURL installed
8. Paste the next cURL command and replace the next variables:
* your-zylon-domain => domain of the zylon instance
* your-zylon-cookie => the `zln_s` cookie you copied in the step 3
* your-integration-id => the `id` you copied in the step 6
* your-user-name => the username of claromentis
* your-new-password-in-raw => the new password for that user in raw
* your-organization => the organization slug,
if you have just 1 organization, is `default` otherwise I'll write down how to get it
```bash theme={null}
curl 'https://{your-zylon-domain}/api/app/integration/claromentis/{your-integration-id}' \
-H 'accept: application/json, text/plain, */*' \
-H 'content-type: application/json' \
-b 'zln_s={your-zylon-cookie}' \
-H 'origin: https://{your-zylon-domain}' \
-H 'x-org: {your-organization}' \
--data-raw '{"username":"{your-user-name}","password":"{your-new-password-in-raw}"}'
```
## Additional Notes
### Linked documents (symlinks) are not supported
Some files in Claromentis may appear in folders but are actually **symlinks**—shortcuts pointing to files stored elsewhere. These are marked with a 🔗 icon in the Claromentis UI.
![claromentis_linked_files.png]()
Zylon does **not** ingest these symlinked documents for the following reasons:
* The **Claromentis API does not support resolving symlinks**, making it impossible to fetch the actual target files.
* Ingesting both the original file and its symlink would create **duplicate content** in Zylon.
* If the **original file is restricted** or not accessible to the user performing the ingestion, ingestion will fail.
* It could lead to **infinite ingestion loops** if symlinks reference each other cyclically.
# Confluence
Source: https://docs.zylon.ai/en/v1.57/operator-manual/knowledge-base/confluence
To integrate with confluence, you need to **create an Atlassian application** that will act as a bridge between Zylon ↔ Confluence and **configure Zylon** to use the brand new Atlassian application
## Create an Atlassian app
First you need an atlassian account that will be the owner of the application. We recommend to use a non personal account. This account does not need to have access to any Space as it will serve as a bridge between Zylon and Confluence.
1. Go to [https://developer.atlassian.com/console/myapps/](https://developer.atlassian.com/console/myapps/)
Click `Create` → `OAuth 2.0 integration`
![image.png]()
1. Provide a meaningful name for the Application.
![image.png]()
1. On distribution:
* In the left menu navigate to `Distribution`
* Click on `Edit`
![image.png]()
1. On distribution status:
* Select the `Sharing` checkbox.
* Enter a vendor name or choose the option `Use your own name`.
* If you have a privacy policy, provide the link to it. If not, use the default link: [`https://example.com/privacy`](https://example.com/privacy), which is intended for internal use.
* For the question "Does your app store personal data?", select `No`
![image.png]()
1. On permissions:
* In the left menu, navigate to **`Permissions`**.
* Click **`Add`** for **`Confluence API`**.
* The page refreshes automatically, and a new **`Configure`** button should appear. If it does not, refresh the page manually.
* Click **`Configure`**.
![image.png]()
![image.png]()
1. Click `Granual scopes` and then on `Edit scopes`
![image.png]()
1. Add one by one the following permissions. You can search them pasting the values into the field with a magnifying glass.
There needs to be a total of `10` scopes added that you can review before saving.
```bash theme={null}
read:content:confluence,
read:content-details:confluence,
read:space-details:confluence,
read:page:confluence,
read:attachment:confluence,
read:blogpost:confluence,
read:custom-content:confluence,
read:space:confluence,
read:space.permission:confluence,
read:folder:confluence,
```
![image.png]()
![image.png]()
1. On authorization:
* In the left menu, navigate to **`Authorization`**.
* Click **`Add`** for **`OAuth 2.0 (3LO)`**.
![image.png]()
1. In authorization:
* In the **`Callback URL`** field, enter:
`https://zylon.company.com/api/app/integration/confluence/callback`Replace **`zylon.company.com`** with the hostname where Zylon is installed on your server.
* Click **`Save changes`**.
![image.png]()
1. On settings:
* In the left menu, navigate to `Settings`. Copy the two values listed under **`Authentication details`**:
* Client ID
* Secret
You will need these values for the next step: [Configure Zylon to use Atlassian Application](https://www.notion.so/Configure-Zylon-to-use-Atlassian-Application-19e00531e9a78026896ae201cb7e2cf3?pvs=21)
![image.png]()
## Configure Zylon to use Atlassian Application
With the values we have acquired in [step 10](https://www.notion.so/ARCHIVED-Confluence-integration-doc-19d00531e9a7809baad3f8131f968d12?pvs=21), you need to edit Zylon config file located in `/etc/zylon/zylon-conf.yaml`
The config file is a `.yaml` file mind indentation, spaces, semicolons, double quotes!
Add the following snippet to the bottom of the file
```bash theme={null}
integration:
confluence:
enabled: true
clientId: ""
clientSecret: ""
redirectUri: ""
```
And fill the properties with the values generated previously:
* clientId → value generated on [step 10](https://www.notion.so/ARCHIVED-Confluence-integration-doc-19d00531e9a7809baad3f8131f968d12?pvs=21)
* clientSecret → value generated on [step 10](https://www.notion.so/ARCHIVED-Confluence-integration-doc-19d00531e9a7809baad3f8131f968d12?pvs=21)
* redirectUri → same value as [step 9](https://www.notion.so/ARCHIVED-Confluence-integration-doc-19d00531e9a7809baad3f8131f968d12?pvs=21)
Save and close `/etc/zylon/zylon-conf.yaml` file
Finally, execute the following command to reset Zylon and update the config
```bash theme={null}
zylon-cli sync
```
You are all set 🎉
## Troubleshooting
### I try to upload files to the knowledge base and Confluence button is greyed out
Clear the browser cache and try again.
### When I click on `Upload files -> From Confluence` the log in is not working
* Check that the `clientId` `secretId` are copy pasted correctly into Zylon config file
* Check that the `Callback URL` is correct in [step 9](https://www.notion.so/ARCHIVED-Confluence-integration-doc-19d00531e9a7809baad3f8131f968d12?pvs=21) and it’s the same as the `redirectUri` in the config file.
### I don’t see any space to import
* Make sure you have logged in into Confluence with an account that has access to spaces.
* Check the permissions required are correct as shown in [step 6](https://www.notion.so/ARCHIVED-Confluence-integration-doc-19d00531e9a7809baad3f8131f968d12?pvs=21)
# Confluence Server
Source: https://docs.zylon.ai/en/v1.57/operator-manual/knowledge-base/confluence-server
Zylon integrates directly with **Confluence Server / Data Center** using the **Confluence REST API**
No Atlassian application, OAuth configuration, or external services are required.
***
## Requirements
* A running *Confluence Data Server* instance
* A **Confluence user account** with access to the Spaces you want to import
* Network access from Zylon to the Confluence instance
***
## Authentication
Zylon authenticates using **Basic Authentication**:
* **Username**: Confluence username
* **Password**: Confluence password
The permissions available to Zylon are exactly the permissions of the user you authenticate with.
***
## Configure Zylon
Edit the Zylon configuration file located at:
```bash theme={null}
/etc/zylon/zylon-conf.yaml
```
The configuration file is YAML. Be careful with indentation, spaces, and quoting.
Add the following configuration:
```yaml theme={null}
integration:
confluenceLocal:
enabled: true
domain: "http://your-confluence-domain:8090"
```
Configuration fields
**enabled**
Enables the Confluence Server connector.
**domain**
Base URL of your Confluence Server instance.
Examples:
[http://confluence.company.local:8090](http://confluence.company.local:8090)
[https://confluence.company.com](https://confluence.company.com)
## Troubleshooting
### I try to upload files to the knowledge base and Confluence button is greyed out
Clear the browser cache and try again.
### When I click on `Upload files -> From Confluence` the log in is not working
* Check that the `domain` copy pasted correctly into Zylon config file
* Check that the `username` and `password` used are correct.
### I don’t see any space to import
* Make sure you have logged in into Confluence with an account that has access to spaces.
# Samba File System
Source: https://docs.zylon.ai/en/v1.57/operator-manual/knowledge-base/file-system
### 1. Gather Your Samba Server Information
To integrate Zylon with your on-premises Samba file server, you need the server’s connection details (host, port, share name) and valid credentials. This guide explains how to configure Zylon to use Samba for file system integration within your local networ. You’ll need:
* **Host or IP address** of the Samba server (e.g. `files.example.com` or `192.168.1.50`).
* **Port** on which SMB is listening (default is `445`; if you run on a non-standard port, note it).
* **Share (root) name** (e.g. `zylon-samba`).
* **Credentials** (username & password) that have **read** access to that share.
* **SMB protocol version support**:
* We currently support **SMB2 and above**.
* If you require **SMB1**, please contact the Zylon team for assistance.
To verify connectivity:
1. **Linux** (using `smbclient`):
```bash theme={null}
smbclient -L //files.example.com -U yourUser%yourPass
```
You should see a listing of shares, including `zylon-samba`.
2. **macOS** (Finder):
* In Finder, press ⌘K → connect to `smb://files.example.com/zylon-samba`.
* Enter your credentials when prompted, and verify you can browse files.
3. Windows
* **File Explorer (Graphical)**:
1. Open **File Explorer** (Win + E).
2. In the left sidebar, right-click **This PC** and choose **Map network drive…**.
3. In the **Drive** dropdown, select an available drive letter (e.g., `Z:`).
4. In the **Folder** field, enter:
(or if using a non-standard port, `\\\\files.example.com@445\\zylon-samba`).
```
\\\\files.example.com\\zylon-samba
```
5. Check **Connect using different credentials**, then click **Finish**.
6. When prompted, enter your Samba **Username** and **Password**, then click **OK**.
7. If the connection succeeds, the new mapped drive (e.g., `Z:`) will appear under **This PC**, and you can browse its contents.
***
### 2. Configure Zylon to Use Samba
With the values we have acquired in previous steps we will edit Zylon config file located in `/etc/zylon/zylon-conf.yaml`
Add the following snippet to the bottom of the file
```yaml theme={null}
integration:
filesystem:
enabled: true
protocol: "samba"
external:
samba:
host: "YOUR_HOST_OR_IP" # e.g. "files.example.com" or "192.168.1.50"
port: 445 # Swap your port if not configured has default
name: "ROOT_PATH"
```
* **host** → The hostname or IP address where your Samba server is reachable.
* **protocol** → Must be set to `"samba"`.
* **root** → Name of the shared folder (e.g. `"Data"`).
Save and close `zylon-conf.yaml`.
***
### 3. Update Zylon to Apply Changes
Finally, execute the following command to reset Zylon and update the config
```bash theme={null}
zylon-cli sync
```
You are all set 🎉
***
### 4. Network Access Considerations (On-Premise)
Since this deployment is on-premise, ensure that the Ubuntu Server where Zylon is hosted can reach the Samba server. You do **not** need to expose SMB to the public internet—everything remains within your private network.
1. **DNS / Hosts Configuration**
* Verify that client machines can resolve the Samba host name (e.g., `files.internal.company`).
* If DNS is unavailable or inconsistent, update `/etc/hosts` (Linux/macOS) or `C:\Windows\System32\drivers\etc\hosts` (Windows) to map the hostname to its IP.
2. **Firewall & Port Access**
* Ensure that **TCP port 445** (or your custom SMB port) is open between client workstations and the Samba server.
* On the Samba server, confirm the OS firewall (iptables, firewalld, Windows Firewall, etc.) allows inbound connections on that port.
* If remote users connect via VPN, make sure the VPN subnet can route to the Samba host’s IP:445.
***
### 5. Credentials
When a user enables Samba integration for the first time via the Zylon front end, they will be prompted to enter:
* **Username**
* **Password**
Zylon verifies these credentials immediately. If they are invalid, the front end displays an error message, and the user must re-enter correct credentials. Once valid, Zylon securely stores the credentials for subsequent access to the share; no manual environment-variable setup is required.
> Note: Credentials are scoped per user account. If multiple users need to connect to the same share, each must enter valid credentials with appropriate access.---
### 6. Troubleshooting
### 6.1 “Cannot resolve host” or “Name or service not known”
* **DNS/Hosts:** Verify that the Samba hostname can be resolved:
```bash theme={null}
ping files.internal.company
```
* If DNS fails, update each client’s hosts file with:
```
192.168.1.50 files.internal.company
```
### 6.2 “Cannot connect to host”
* **Port Reachability:**
```bash theme={null}
nc -vz files.internal.company 445
```
(or replace `445` with your custom port).
* If test fails, confirm firewall rules on both the client network segment and the Samba server.
### 6.3 Authentication Failed / Wrong Credentials
* If a user enters incorrect Samba credentials in the Zylon front end, they will see an immediate error like “Authentication failed: invalid username or password.”
* To correct, the user should re-enter their valid Samba username and password via the integration UI.
* On the Samba server side, verify that the account exists and has permissions in `/etc/samba/smb.conf`:
```bash theme={null}
sudo smbpasswd -a yourUser
testparm -s
sudo tail -f /var/log/samba/log.smbd
```
### 6.4 “Invalid protocol version”
* Ensure your server and Zylon both support **SMB2 or higher**.
* To force SMB2+ on the server, add under `[global]` in `/etc/samba/smb.conf`:
```
server min protocol = SMB2
```
Then restart Samba:
```bash theme={null}
sudo systemctl restart smbd
```
* If you must use SMB1, contact the Zylon team for a custom client build.
***
### 8. Additional Notes
* **Only Samba (SMB) Is Supported for File System Integrations**
At this time, Zylon’s integration framework supports **only SMB2+ file system mounts**. If you require a different protocol (e.g., NFS, FTP, WebDAV), contact the Zylon team.
* **SMB1 Support**
SMB1 is deprecated and insecure. If your environment still requires SMB1, reach out to us. We can provide guidance or build a compatible client.
* **Performance Tips**
* For large repositories, ensure your Samba server has sufficient I/O and network bandwidth.
* On Linux, mounting with `cache=none` can reduce stale‐file issues if users frequently modify files outside Zylon.
You are now ready to integrate Zylon with your Samba file system. Once connected, users will be able to browse and manage shared files directly from the Zylon interface.
# Google Drive
Source: https://docs.zylon.ai/en/v1.57/operator-manual/knowledge-base/google-drive
To integrate with Google Drive, create a Google Cloud OAuth application and configure Zylon with its credentials. This enables users to sign in with Google, select files or folders through the Google Picker, and import them into a knowledge base.
## Before you begin
* Use a Google account that can manage the Google Cloud project. It does not need access to the Drive content that users will import.
* Know the public URL of your Zylon instance, for example `https://zylon.company.com`.
* Keep the OAuth client secret in a secure secret store. Do not commit it to source control. The Picker API key is used by the browser, so restrict it to the required APIs and, where applicable, your Zylon origin.
## Create or select a Google Cloud project
1. Open the [Google Cloud console](https://console.cloud.google.com/).
2. Select an existing project or create a new project for the integration.
3. Record the **Project number** from the project dashboard. Zylon uses this as the Picker **App ID**.
\[Placeholder: Add a screenshot showing the Google Cloud project number.]
## Enable the Google APIs
1. In the Google Cloud console, go to **APIs & Services** → **Library**.
2. Search for and enable **Google Drive API**.
3. Search for and enable **Google Picker API**.
![Google Cloud API Library search results]()
## Create and restrict an API key
The Google Picker requires an API key in addition to the OAuth client credentials.
1. Go to **APIs & Services** → **Credentials**.
2. Select **Create credentials** → **API key**.
3. Copy the key; it is the value for Zylon's `apiKey` setting.
4. Open the new key and, under **API restrictions**, select **Restrict key**.
5. Select **Google Drive API** and **Google Picker API**, then save the key.
If your Google Cloud policy requires application restrictions, restrict the key to the public origin of your Zylon Workspace, for example `https://zylon.company.com`.
![API key restricted to Google Drive API and Google Picker API]()
## Configure the OAuth consent screen and data access
1. In the Google Cloud console, open **Google Auth platform**. Complete the required **Branding** and **Audience** settings for your organization.
2. Open **Data Access** and select **Add or remove scopes**.
3. Add the following scopes, then save the changes.
| Scope | User-facing description |
| - | - |
| `https://www.googleapis.com/auth/drive.metadata.readonly` | View metadata for files in your Google Drive. |
| `https://www.googleapis.com/auth/drive.readonly` | View and download files from your Google Drive. |
| `https://www.googleapis.com/auth/userinfo.email` | See your primary Google Account email address. |
| `https://www.googleapis.com/auth/userinfo.profile` | See your personal info, including any personal info you have made publicly available. |
| `openid` | Associate you with your personal info on Google. |
| `https://www.googleapis.com/auth/drive.file` | See, edit, create, and delete only the specific Google Drive files you use with this app. |
Zylon requests all of these scopes during sign-in. The Drive metadata scope is required by the connector implementation as well as the Drive read-only scope.
![Google Auth platform Data Access scopes]()
## Create an OAuth client
1. In **Google Auth platform**, open **Clients**.
2. Select **Create client** and choose **Web application** as the application type.
3. Give the client a meaningful name, such as `Zylon Google Drive`.
4. Under **Authorized redirect URIs**, add the following URL, replacing the domain with your Zylon instance URL:
```text theme={null}
https://{your-zylon-domain}/api/app/integration/googledrive/callback
```
5. Create the client.
6. Copy the **Client ID** and **Client secret**. You will use them as `clientId` and `clientSecret` in the Zylon configuration.
The redirect URI in Google Cloud and Zylon must match exactly, including `https`, domain, path, and trailing slash behavior.
![Google OAuth client configuration]()
## Configure Zylon
Add the following values to your Zylon configuration. The same `apiKey` and `appId` values are made available to the Workspace frontend for the Google Picker.
```yaml theme={null}
integration:
googleDrive:
enabled: true
clientId: "{Google OAuth client ID}"
clientSecret: "{Google OAuth client secret}"
redirectUri: "https://{your-zylon-domain}/api/app/integration/googledrive/callback"
apiKey: "{Google API key}"
appId: "{Google Cloud project number}"
```
For Helm installations, set the equivalent values in your values file under `integration.googleDrive`:
```yaml theme={null}
integration:
googleDrive:
enabled: true
clientId: "{Google OAuth client ID}"
clientSecret: "{Google OAuth client secret}"
redirectUri: "https://{your-zylon-domain}/api/app/integration/googledrive/callback"
apiKey: "{Google API key}"
appId: "{Google Cloud project number}"
```
Apply the configuration using your normal Zylon deployment process. For installations managed with the Zylon CLI, run:
```bash theme={null}
sudo zylon-cli sync
```
You are ready to connect Google Drive from a project knowledge base.
## Troubleshooting
### The Google Drive option is unavailable or the picker closes immediately
* Confirm that `integration.googleDrive.enabled` is `true`.
* Confirm that `apiKey` and `appId` are configured. The Picker requires both values.
* Confirm that the Google Drive API and Google Picker API are enabled in the same Google Cloud project.
### Google sign-in reports a redirect URI error
* Verify that the **Authorized redirect URI** is exactly the same as `redirectUri` in the Zylon configuration.
* Confirm that the domain is the public HTTPS domain used to access Zylon.
### A user cannot see or import a Drive item
* Confirm that the user signs in with the Google account that can access the item.
* Confirm that the consent screen includes all scopes listed in [Configure the OAuth consent screen and data access](#configure-the-oauth-consent-screen-and-data-access).
# Knowledge Connectors
Source: https://docs.zylon.ai/en/v1.57/operator-manual/knowledge-base/overview
Configure Google Drive access so users can select and index files and folders from their Google accounts
Connect to Atlassian Confluence spaces to index wiki pages, documentation, and collaborative content
Integrate with Microsoft SharePoint sites to access documents, lists, and team collaboration content
Configure Claromentis intranet connector to index internal company knowledge and digital workplace content
Set up file share integration to index network drives and shared file system content. E.g. Samba
# SharePoint
Source: https://docs.zylon.ai/en/v1.57/operator-manual/knowledge-base/sharepoint
To integrate with SharePoint, you need to **create a Microsoft Entra application** that acts as a bridge between Zylon ↔ SharePoint and **configure Zylon** to use this Microsoft application.
This guide walks you through integrating SharePoint with Zylon using Microsoft’s OAuth 2.0. This enables Zylon to securely access your SharePoint resources using delegated permissions.
## Create a Microsoft Entra app
First you need a Microsoft Entra application. We recommend to use a non-personal account to create this from the Microsoft Entra panel. This account does not need to have access to any items on SharePoint but has the right permissions to setup the app that will serve as a bridge between Zylon and SharePoint.
1. Go to [https://entra.microsoft.com](https://entra.microsoft.com/).
On the left sidebar Click `Applications` → `App Registrations` → `New Registration`
![imagen.png]()
2. Provide a meaningful name for the Application.
3. On Supported Account types choose `Accounts in this organizational directory only`
4. Under `Redirect URI` → Select `Web` and add the followings redirect URL
```
https://{your-zylon-instance}.com/api/app/integration/sharepoint/callback
```
1. Click `Register`
![Screenshot 2025-04-07 at 11.23.17.png]()
2. Click on `Redirect URIs`
![image.png]()
3. Click on `Add a platform`
![image.png]()
4. Click on `Single-Page application`
![image.png]()
5. Add the following URL and click `Configure`:
```
https://{your-zylon-instance}.com
```
6. Now that the app is created, note the `Application (client) Id` and `Directory (tenant) id` from the `Overview` page.
![image.png]()
7. Let’s create an application secret
Navigate to `Certificates & secrets` → Click `+ New client secret` → Add a description and expiration date(if you add a date coming up shortly you have to be aware your integration will stop working when the secret expires)
Copy the Client Secret`value`. The secret value will not be accesible later.
![imagen.png]()
Now we have to configure the API permissions our client application will have.
Navigate to `API Permissions` → `+ Add a permission` → `Microsoft Graph` → `Delegated permissions` and include the permissions below then click on `Add permissions`
* `Files.Read.All`
* `OpenId permissions.offline_access`
* `SharePointTenantSettings.Read.All`
* `Sites.Read.All`
* `User.Read`
Navigate to `API Permissions` → `+ Add a permission` → `SharePoint` → `Delegated permissions` and include the permissions below then click on `Add permissions`
* `AllSites.Read`
* `EnterpriseResource.Read`
* `MyFiles.Read`
* `Project.Read`
* `Sites.Search.All`
* `User.Read.All`
After adding both list of permissions click on `Grant admin consent for [Your Org]` and confirm by clicking `Yes`
![image.png]()
## Configure Zylon with your Azure AD app
With the values we have acquired in previous
steps we will edit Zylon config file located in `/etc/zylon/zylon-conf.yaml`
Add the following snippet to the bottom of the file
```bash theme={null}
integration:
sharepoint:
enabled: true
clientId: "" //From step 10 - Application client Id
clientSecret: "" //From step 11 - Secret value
redirectUri: "" //From step 4
domain: "" //Your sharepoint domain. ex: https://zylonai.sharepoint.com
tenantId: "" //From step 10 - Directory tenant Id
entrySite: "" //Optional: Default Entry SharePoint site URL
entryList: "" //Optional: Default Entry list name (e.g., "Documents")
entryFolder: "" //Optional: Default Entry folder name
```
And fill the properties with the values generated previously:
* clientId → value generated on step 10
* clientSecret → value generated on step 11
* redirectUri → same value as step 4
* domain → Your sharepoint url
* tenantId → same value as step 10
* entrySite → (Optional) Default SharePoint site URL. See [Configuring Default Opening Folder](#configuring-default-opening-folder) section below
* entryList → (Optional) Default list name, e.g., "Documents". See [Configuring Default Opening Folder](#configuring-default-opening-folder) section below
* entryFolder → (Optional) Default folder name. See [Configuring Default Opening Folder](#configuring-default-opening-folder) section below
Save and close `/etc/zylon/zylon-conf.yaml` file
Finally, execute the following command to reset Zylon and update the config
```bash theme={null}
sudo zylon-cli sync
```
You are all set 🎉
## Configuring Default Opening Folder
You can configure a default opening folder for the SharePoint integration. This allows the integration to open directly to a specific folder when users access SharePoint through Zylon, improving the user experience by skipping navigation steps.
The three optional fields control the entry point for the integration:
* `entrySite`: The absolute SharePoint site URL (works for both SharePoint and OneDrive)
* `entryList`: The list name within the site (e.g., "Documents" is the default for SharePoint)
* `entryFolder`: The folder name within the list
**Important:** You must use absolute SharePoint paths for the `entrySite` field, even for OneDrive. The path format should be like:
```
https://example-my.sharepoint.com/personal/user_example_onmicrosoft_com
```
### Example Configuration
If you want the integration to open by default to the "Defense and Security" folder in the Documents list for the user `user_example_onmicrosoft_com`, you would configure:
```bash theme={null}
entrySite: "https://example-my.sharepoint.com/personal/user_example_onmicrosoft_com"
entryList: "Documents" //Default on SharePoint
entryFolder: "Defense and Security"
```
This configuration will make the integration open directly to the "Defense and Security" folder when users access SharePoint through Zylon.
**Note:** All three fields are optional. If they are not set or left empty, they will be ignored and the integration will use the default behavior (opening at the root level).
## Troubleshooting
### I tried to upload files to the knowledge base but the SharePoint button is greyed out
Clear the browser cache and try again.
### When I click on `Upload files -> From SharePoint` the log in is not working
* Check that the `clientId` `secretId` are copy pasted correctly into Zylon config file
* Check that `redirectUri` is the same as step 4 and that your domain from sharepoint is right
* Check that the `tenantId` being used matches the one under the `Overview` page of your application on Azure AD
# Google Integration (SSO)
Source: https://docs.zylon.ai/en/v1.57/operator-manual/openid/google
### Create a new Oauth application for Zylon
In order to enable Google SSO for Zylon, you need to create an OAuth 2.0 application in the Google Cloud Console.
Navigate to the [Google Cloud Console](https://console.cloud.google.com/).
You might need to create a new Google project for Zylon if you don't have one already to host the OAuth application.
![create-project]()
Navigate to the [Google Auth Section](https://console.cloud.google.com/auth/), to create the app.
![create-oauth-app]()
![oauth-config]()
For the audience configuration, set it to internal so only users from your organization can log in,
otherwise you will need to go through Google's verification process.
### Configure the Oauth client
Next, configure the Oauth client
![oauth-client-id]()
Make sure of the following settings:
* The application type is set to **Web application**.
* The allowed JavaScript origins is set to `https://zylon.company.com`, replacing `zylon.company.com` with the domain where Zylon is hosted (It is the same domain as the host in the config file located in `/etc/zylon/zylon-conf.yaml`).
* The authorized redirect URI is set to `https://zylon.company.com/api/v1/auth/google/callback`, same as above replace `zylon.company.com` with the domain where Zylon is hosted.
* Apply the changes and save the `Client ID` and `Client Secret` that will be used later in the config file for Zylon.
Select **Web application** as the application type:
![oauth-web-app]()
Set the authorized redirect URI as mentioned before, double check that the domain is correct
and the suffix is `/api/v1/auth/google/callback`:
![oauth-redirect-uri]()
Create the OAuth client and save the `Client ID` and `Client Secret`:
![oauth-client-created]()
### Grant openid scope
Navigate to the [Data Access/Scopes section](https://console.cloud.google.com/auth/scopes), and add the following scopes to your application:
* auth/userinfo.email (To get the user email)
* auth/userinfo.profile (To get user's name and profile picture)
* openid (To authenticate users with OpenID Connect)
![oauth-scopes]()
![oauth-scopes-added]()
### Add the configuration to Zylon
Add the following configuration to `/etc/zylon/zylon-conf.yaml`,
replacing the `clientId` and `clientSecret` values with the ones obtained in the previous steps
and the `redirectUri` with the correct domain where Zylon is hosted.
The config file is a `.yaml` file so indentation, spaces, semicolons, double quotes are very important
```yaml theme={null}
auth:
google:
enabled: true
clientId: "1234567890-abcde.apps.googleusercontent.com"
clientSecret: "GOCSPX-xxxxxxxxxxxxxxxxxxxxxxxx"
redirectUri: "https://zylon.company.com/api/v1/auth/google/callback"
```
Run the following command to refresh the configuration
```yaml theme={null}
sudo zylon-cli sync
```
Now you should see the Google SSO option when logging in.
In case you don’t see the Google button to log in, clear the browser cache.
# Microsoft Entra Integration (SSO)
Source: https://docs.zylon.ai/en/v1.57/operator-manual/openid/microsoft
### Add a new application for Zylon
The objective is to obtain 3 values that will be used to configure Zylon to be able log in with a Microsoft Account.
* `Application (client) ID`
* `Client Secret`
1. First of all you need to login into [https://portal.azure.com/#home](https://portal.azure.com/#home) console dashboard
2. Click `Microsoft Entra Id`
![image.png]()
3. Register a new App. Click on `App registrations` on the left menu.
![image.png]()
4. Click on `New Registration`.
![image.png]()
1. A new window will open and you will need to add the following information
* ⚠️ Redirect URI type is **web**⚠️
* Domain: `https://zylon.company.com/api/v1/auth/microsoft/callback`. Replace `zylon.company.com` with the domain where Zylon is hosted (It is the same domain as in the config file located in `/etc/zylon/zylon-conf.yaml`).
* Supported account types: All account types are supported. Choose based on your specific needs.
![image.png]()
* In case you want to change it later you can do so in the `Application Overview`
![image.png]()
5. Save the following value that will be used later in the config file for Zylon.
* Application (client) ID
![image.png]()
6. Now we need to generate the `ClientSecret`. Go to the left menu and click `Manage > Certificates & secrets`
![image.png]()
7. Click on `New client secret` and add the required information
![image.png]()
8. Copy the `Value` for client secret.
![image.png]()
9. Verify that the `User.read` permission is granted. Click on `API Permissions` on the left menu. You should see it there by default. In case it is missing, grant it.
![image.png]()
10. Add the following configuration to `/etc/zylon/zylon-conf.yaml`
The config file is a `.yaml` file so indentation, spaces, semicolons, double quotes are very important
```yaml theme={null}
auth:
microsoft:
enabled: true
redirectUri: "https://zylon.company.com/api/v1/auth/microsoft/callback"
tenantId: "common"
clientId: "8c7d......"
clientSecret: ".RS8Q~....."
```
Run the following command to refresh the configuration
```yaml theme={null}
sudo zylon-cli sync
```
Now you should see the Microsoft Account SSO
In case you don’t see the Microsoft Account button to log in, clear the browser cache.
### How to manage users
To limit the number of users that are able to log into Zylon check the following link, by default everybody in the Directory can access Zylon and will be granted the `member` role
[https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/what-is-access-management](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/what-is-access-management)
# Backups and Disaster Recovery
Source: https://docs.zylon.ai/en/v1.57/operator-manual/operations/backup
Zylon is prepared to be fully backed up and restored in case of hardware failure or disaster recovery situations.
There are multiple ways to approach the problem: a single full disk copy and a Velero based solution.
## Full disk backup
Since most Zylon installations run in a single node, it’s perfectly valid to do a traditional full disk backup with a tool like Clonezilla or similar.
Store the image in a cold storage and in case of recovery simply replace the disk contents. Zylon should went back to the moment in the time the snapshot was taken.
Note that this is only possible if Zylon is running in a single kubernetes node; multi node setups MUST use Velero as a backup strategy.
## Data backup using the zylon-cli
### Backup command:
`sudo zylon-cli backup [--keep-last N]`
Will take a snapshot of Zylon data and save it it to the local machine.
### Restore command:
`sudo zylon-cli restore [--backup-file path-to-backup]`
Will restore Zylon state to the moment in time the snapshot was taken. By default, the latest backup will be used, but a given snapshot can be specified too.
This basic backups will snapshot Zylon state and save the contents as a .tar.gz to the `/var/backups/zylon` folder with the date of the backup as file name.
You should consider copying backup files file to a different machine in case of disk failure.
By default, only the last 10 backups are preserved.
**During the backup process, Zylon will be offline.** Depending on the amount of documents you have uploaded this process might take several minutes.
### Putting backups on schedule
You can add this backups on a schedule automatically, run `sudo crontab -e` to open the cron editor and add the backup like
For example, this backup will be performed every Saturday at 4am
```jsx theme={null}
0 4 * * 6 sudo zylon-cli backup --keep-last 5 -y >> /var/log/zylon-backup.log 2>&1
```
## Velero
[Velero](https://velero.io/) is the standard way to backup kubernetes clusters. It allows automation and only backs up the required cluster and application information.
> Note that in case of disk failure a Velero backup won’t restore the cluster, Nvidia drivers, and other tools required to run Zylon. To recover from that scenario perform a regular setup of Zylon followed by the backup restoration process.To enable Velero backups you **must:**
### 1. Install Velero CLI
```bash theme={null}
https://velero.io/docs/v1.3.0/velero-install/
```
After the command succeeds, the `velero` binary should be available in your path.
### 2. Provide a valid object storage solution.
This is the storage where the backups will be stored and ideally should be a completely separate machine.
A list of common providers are:
* AWS s3
* Google Cloud Storage
* Azure Blob storage
* A self hosted minio server
* Full list of providers here: [https://velero.io/docs/v1.15/supported-providers/](https://velero.io/docs/v1.15/supported-providers/)
A initial backup of Zylon will take a minimum of 20GB of storage and will grow as you upload documents and generate more data.
Check the `setup instructions` for your provider of choice at the table [https://velero.io/docs/v1.15/supported-providers/](https://velero.io/docs/v1.15/supported-providers/).
You might need to follow several steps like creating a AWS user in case of s3, configuring some permissions and so on. If you need guidance during the process contact the Zylon team.
### 3. Install Velero in the Zylon kubernetes cluster
Velero CLI will take care of *most* of the work to enable backups inside the cluster. However, in order to properly backup Zylon using Velero, several flags MUST be passed during the installation, in particular these flags are mandatory:
```bash theme={null}
--features=EnableCSI
--use-node-agent
```
For example, a installation of Velero that uses AWS S3 as storage will have a configuration file located in `/etc/zylon/velero.txt` with the content:
```bash theme={null}
[default]
aws_access_key_id = AKIA5...
aws_secret_access_key = kuBsP9dc0...
```
Then Velero will be installed with the following command:
```bash theme={null}
velero install --provider aws \
--bucket backup \
--secret-file /etc/zylon/velero.txt \
--plugins velero/velero-plugin-for-aws:v1.10.0 \
--backup-location-config region=us-east-1 \
--use-volume-snapshots=true \
--features=EnableCSI \
--use-node-agent \
--snapshot-location-config region=us-east-1,s3ForcePathStyle="true"
```
The process is slightly different for each provider, make sure you are selecting the right velero plugin, proper credentials and that the mandatory flags required by Zylon are passed.
### 4. Patch Velero for k0s
Zylon uses k0s internally as a kubernetes cluster. Velero needs a small patch to enable backups. Run the following command so Velero can discover all the pods that need to be backed up:
```bash theme={null}
kubectl patch daemonset node-agent \
--namespace velero --type='json' -p='[{"op": "replace", "path": "/spec/template/spec/volumes/0/hostPath/path", "value": "/var/lib/k0s/kubelet/pods"}]'
```
### 5. Create a backup of the Zylon namespace
Backup process creation also requires mandatory flags, in this case, the following flags MUST be passed
```bash theme={null}
--include-namespaces zylon
--default-volumes-to-fs-backup
```
For example, setting up a initial backup could be done by running:
```bash theme={null}
velero backup create my-first-backup --include-namespaces zylon --default-volumes-to-fs-backup
```
There are many backup and restoration strategies that go beyond the scope of this manual, for more information about them refer to the official docs: [https://velero.io/docs/v1.15/](https://velero.io/docs/v1.15/)
# Store Zylon Data on a Separate Disk
Source: https://docs.zylon.ai/en/v1.57/operator-manual/operations/data-disk
Move Zylon's data directory to a dedicated disk or partition for additional storage capacity.
Zylon stores its application data under `/var/zylon`. By default, this directory lives on the same disk as the operating system. As your deployment grows, you may need to move that data to a larger or dedicated disk.
This guide walks through relocating Zylon data to a separate disk or partition without reinstalling the platform.
## When to use this guide
Use this procedure when:
* The OS disk is running low on space but you have an additional disk available.
* You want to isolate Zylon data on dedicated storage for performance or operational reasons.
* You are preparing the server for a storage layout change (for example, before enabling [disk encryption](/en/v1.57/operator-manual/instance-hardening/disk-encryption)).
## What gets moved
Zylon's persistent state is stored under `/var/zylon`, including:
* Uploaded documents and knowledge-base content
* Databases
* Dependencies (drivers, binaries), stored in `artifacts`
* AI models
* Kubernetes persistent volumes managed by Zylon
You can choose which directories under `/var/zylon` to move based on what is consuming the most space on your server. The same bind-mount approach works for any path listed above.
**Back up before you begin.** This is a high-risk operation; data loss is possible if anything goes wrong.
Create a backup and verify you can restore it before continuing:
```bash theme={null}
sudo zylon-cli backup
```
Copy the resulting backup file to a safe external location and confirm you can access it.
See the [Backup guide](/en/v1.57/operator-manual/operations/backup) for details.
***
## Overview
This procedure moves selected data directories to a dedicated disk while keeping the rest of `/var/zylon` on the OS volume. Zylon continues to use the same paths (for example, `/var/zylon/artifacts` and `/var/zylon/ai-models`). **Bind mounts** in `/etc/fstab` redirect those paths to the new disk, so no application configuration changes are required.
At a high level, you will:
1. **Identify the target disk**: find an unused disk or partition with enough space for current and future data.
2. **Prepare the disk**: partition it (if needed), format it with ext4, and mount it at `/mnt/data`.
3. **Stop Zylon**: shut down the Kubernetes cluster with `sudo k0s stop` so files are not in use during the copy.
4. **Migrate the data**: copy the chosen directories from `/var/zylon` to the new disk.
5. **Configure bind mounts**: add entries to `/etc/fstab` so the new disk paths are mounted back at their original locations under `/var/zylon` on every boot.
6. **Start Zylon and verify**: bring the cluster back up and confirm Zylon is healthy.
7. **Remove old data**: once verified, delete the original copies on the OS disk and remount the bind mounts.
**Expect downtime during the migration.** Zylon must be stopped while data is copied and mounts are reconfigured. The duration depends on how much data you are moving.
***
## Step 1: Identify the target disk
Run `lsblk` to see which disks are attached to the server. You need a device that is not already in use (no mount points listed) and has enough space for your Zylon data:
```bash theme={null}
lsblk
```
In our example, the output looks like this:
```
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS
loop0 7:0 0 27.6M 1 loop /snap/amazon-ssm-agent/11797
loop1 7:1 0 28.2M 1 loop /snap/amazon-ssm-agent/13009
loop2 7:2 0 73.9M 1 loop /snap/core22/2045
loop3 7:3 0 74M 1 loop /snap/core22/2411
loop4 7:4 0 49.3M 1 loop /snap/snapd/24792
loop5 7:5 0 49.3M 1 loop /snap/snapd/26865
nvme1n1 259:0 0 300G 0 disk /
nvme0n1 259:1 0 300G 0 disk
```
In this example, we use `nvme0n1` as the target. Replace `/dev/nvme0n1` with your actual device in every command below.
***
## Step 2: Prepare the target disk
Create a mount point and configure the target disk to mount automatically at boot. If the disk is already partitioned and formatted, skip the partitioning and formatting commands below and go straight to creating the mount point.
Partitioning and formatting **erase all data** on the target disk. Only run these commands on a blank disk, or when you are certain the device has no data you need to keep. Double-check you have selected the correct device before proceeding.
If the disk is not already partitioned and formatted, run the following to set it up with ext4:
```bash theme={null}
sudo parted /dev/nvme0n1 mklabel gpt
sudo parted /dev/nvme0n1 mkpart primary 0% 100%
sudo mkfs.ext4 /dev/nvme0n1
```
Create the mount point on the new disk:
```bash theme={null}
sudo mkdir -p /mnt/data
```
Get the disk UUID so the mount survives reboots:
```bash theme={null}
sudo blkid /dev/nvme0n1
```
The output will look similar to:
```
/dev/nvme0n1: UUID="2c2f893d-6ce5-4eb5-8e0a-3b85b4894814" BLOCK_SIZE="4096" TYPE="ext4"
```
Add an entry to `/etc/fstab` using your UUID (replace the value below with the one from your output):
```bash theme={null}
echo 'UUID=2c2f893d-6ce5-4eb5-8e0a-3b85b4894814 /mnt/data ext4 defaults 0 2' | sudo tee -a /etc/fstab
```
Reload systemd and mount the disk:
```bash theme={null}
sudo systemctl daemon-reload
sudo mount -a
```
Confirm the disk is mounted:
```bash theme={null}
df -h /mnt/data
```
***
## Step 3: Stop Zylon
Stop the Kubernetes cluster so no processes are reading or writing the directories you are about to migrate:
```bash theme={null}
sudo k0s stop
```
Wait until the command completes before continuing.
***
## Step 4: Migrate data to the new disk
You can decide which directories under `/var/zylon` to move to the new disk. Choose the paths that are using the most space or that you want to keep separate from the OS volume. In this example, we move Zylon dependencies and AI models. Dependencies are stored in the `artifacts` directory.
```bash theme={null}
sudo cp -a /var/zylon/artifacts/. /mnt/data/zylon/artifacts/
sudo cp -a /var/zylon/ai-models/. /mnt/data/zylon/ai-models/
```
Verify the copy completed and the file counts look reasonable:
```bash theme={null}
du -sh /var/zylon/artifacts /mnt/data/zylon/artifacts
du -sh /var/zylon/ai-models /mnt/data/zylon/ai-models
```
The sizes on the source and destination should match.
***
## Step 5: Point Zylon to the new location
Add bind mount entries to `/etc/fstab`. These make Linux present the data on the new disk at the original paths Zylon expects:
```bash theme={null}
echo '/mnt/data/zylon/artifacts /var/zylon/artifacts none bind 0 0' | sudo tee -a /etc/fstab
echo '/mnt/data/zylon/ai-models /var/zylon/ai-models none bind 0 0' | sudo tee -a /etc/fstab
sudo systemctl daemon-reload
sudo mount -a
```
Confirm both bind mounts are active:
```bash theme={null}
sudo findmnt /var/zylon/artifacts
sudo findmnt /var/zylon/ai-models
```
Each command should show the mount source pointing to `/mnt/data/zylon/...`.
***
## Step 6: Start Zylon and verify
Start the cluster and confirm Zylon is working normally:
```bash theme={null}
sudo k0s start
```
Log in to the workspace and run a query that uses AI models to confirm both directories are being served from the new disk.
***
## Step 7: Remove old data
Once you have verified Zylon is healthy, remove the original copies from the OS disk to reclaim space. This step requires stopping Zylon again and temporarily unmounting the bind mounts.
Stop Zylon:
```bash theme={null}
sudo k0s stop
```
Unmount the bind mounts (this does not affect the data on `/mnt/data`):
```bash theme={null}
sudo umount /var/zylon/ai-models
sudo umount /var/zylon/artifacts
```
Confirm they are no longer mounted:
```bash theme={null}
sudo findmnt /var/zylon/ai-models
sudo findmnt /var/zylon/artifacts
```
Both commands should return no results.
Remove the old data and recreate the empty mount-point directories:
```bash theme={null}
sudo rm -rf /var/zylon/ai-models
sudo rm -rf /var/zylon/artifacts
sudo mkdir /var/zylon/ai-models
sudo mkdir /var/zylon/artifacts
```
Reapply the bind mounts from `/etc/fstab`:
```bash theme={null}
sudo mount -a
```
Confirm the bind mounts are back:
```bash theme={null}
sudo findmnt /var/zylon/ai-models
sudo findmnt /var/zylon/artifacts
```
Start Zylon:
```bash theme={null}
sudo k0s start
```
# Sys Admin Dashboard
Source: https://docs.zylon.ai/en/v1.57/operator-manual/operations/sys-admin-dashboard
Monitor and manage system health, performance, and user activities with the Sys Admin Dashboard.
Zylon comes with a built-in [Kubernetes Dashboard](https://kubernetes.io/docs/tasks/access-application-cluster/web-ui-dashboard/),
which will help you monitor and diagnose issues with your installation.
To enable it, you will need to edit your config file at `/etc/zylon/zylon-conf.yaml` and add the following section:
```yaml theme={null}
adminDashboard:
enabled: true
exposeIngress: true
```
Next, update your Zylon system by running:
```bash theme={null}
sudo zylon-cli sync
```
Once the update completes, access the dashboard at:
`https:///kube-dashboard`
To login, you can generate a short-lived token:
```bash theme={null}
kubectl -n zylon create token zylon
```
Or a permanent token:
```bash theme={null}
kubectl get secret zylon-token -n zylon -o jsonpath='{.data.token}' | base64 -d
```
The permanent token will provide full admin access to your Kubernetes cluster.
Keep it secret and secure.
Zylon uses multiple namespaces, you can check the status of each.
Select the right namespace from the dropdown on the top left corner.
* zylon: Zylon system components
* openebs: OpenEBS storage system
* nvidia: NVIDIA controller and device plugin
After logging in, you will be able to see the status of your Zylon installation, including:
* Pods
* Logs
* Basic metrics regarding CPU and memory usage
## Frequent Questions
This section explains how to navigate the Kubernetes Dashboard to investigate common issues in your Zylon installation.
### ❓ Where do I start when something is not working?
When you first open the Kubernetes Dashboard, you'll see a high-level overview of your workloads and cluster health.
This view shows the current status of running resources such as Pods, Deployments, and basic CPU/memory usage.
![image]()
***
### ❓ Which namespace should I select?
Zylon uses multiple namespaces, but most workspace and platform issues will be in the `zylon` namespace.
1. Open the namespace dropdown in the **top-left corner** of the dashboard
2. Select the namespace you want to check
3. The dashboard will refresh and show only that namespace's system components
This helps reduce noise and ensures you are inspecting the correct resources.
![image]()
***
### ❓ How do I view logs for a Pod?
To inspect logs for a specific Pod:
1. Click on the **Pod name** you want to investigate
2. This opens the Pod details page with:
* Status
* Events
* Resource usage
* Containers
3. In the **top-right corner**, click **Logs**
![image]()
You can:
* View live logs
* Download logs for offline analysis if your instance is airgap
Logs are usually the fastest way to identify configuration errors, startup failures, or runtime issues.
# Authentication for Sensitive Actions
Source: https://docs.zylon.ai/en/v1.57/operator-manual/security/authentication-for-sensitive-actions
Compliance reference for actions protected by authentication freshness.
Zylon can require a recent authentication challenge before a principal performs a sensitive workspace or backoffice action. This control adds a time-bound reauthentication requirement on top of the user's existing permissions and authorization checks.
Authentication freshness is not applied to API requests authenticated with tokens. Token-based integrations do not need additional reauthentication steps or changes to their existing flows.
The feature can be [enabled and configured by risk level](/en/v1.57/operator-manual/configuration/features/authentication-freshness). When enabled, the action-specific challenge is valid only for the configured freshness window. The low, medium, and high windows are independent.
## Protected actions
The following table reflects the current backend call sites of `assertPrincipalAuthChallengeIsValid`. The list is a code-level reference and should be reviewed after changes to sensitive authorization paths.
| Area | Protected action | Backend method | Risk level |
| - | - | - | - |
| Organization | Create an organization | `createOrganization` | Medium |
| Organization | Delete an organization, including its content | `deleteOrganization` | High |
| Organization | Update organization settings | `updateOrganization` | Low |
| Gateway | Create a gateway | `createGateway` | High |
| Gateway | Delete a gateway | `deleteGateway` | High |
| Gateway users | Add a user to a gateway | `addUserToGateway` | Medium |
| Gateway users | Change a gateway user's role | `updateUserRole` | Medium |
| Gateway users | Activate a gateway user | `setGatewayUserState` | Low |
| Gateway users | Deactivate a gateway user | `setGatewayUserState` | High |
| Gateway users | Remove a user from a gateway | `removeGatewayUser` | Medium |
| Project | Transfer project ownership | `transferProjectOwnership` | Medium |
| Project | Update project settings | `updateProject` | Low |
| Project | Add project members | `addMembersToProject` | Medium |
| Project | Update project member roles | `updateMemberRoles` | Medium |
| Project | Remove a project member | `removeMemberFromProject` | Medium |
| Project | Soft-delete a project | `deleteProject` | High |
| Project | Hard-delete a project | `hardDeleteProject` | High |
| API tokens | Create an API token | `createApiToken` | High |
| API tokens | Delete an API token | `deleteTokenByHash` | High |
| Artifacts | Create connector artifacts | `createArtifact` | Low |
| Artifacts | Delete artifacts | `deleteArtifactsById` | High |
| Artifacts | Delete an ingested document and its entity | `scheduleDeleteVectorsAndEntity` | High |
| Users | Change a user's role | `updateUser` | Medium when retaining or reducing privilege; High when granting a higher role |
| Users | Add a user to an organization | `addUserToOrganization` | High |
| Users | Activate a user | `setUserState` | High |
| Users | Deactivate a user | `setUserState` | Medium |
| Accounts | Activate an account | `updateAccount` | High |
| Accounts | Deactivate an account | `updateAccount` | Low |
API-token principals are exempt from this freshness check by design. This does not bypass the endpoint's normal permission, scope, or ownership checks.
## Authentication methods and failure handling
For interactive users, the frontend can answer an authentication challenge with the configured password or SSO flow. A missing or expired challenge prevents the protected action from proceeding until the user authenticates again. Google and Microsoft SSO may redirect the browser away from the original request; operators should account for the possibility that the user needs to repeat the action after returning.
For configuration details and the exact freshness windows, see [Authentication Freshness](/en/v1.57/operator-manual/configuration/features/authentication-freshness).
# AI Inference Performance
Source: https://docs.zylon.ai/en/v1.57/operator-manual/troubleshooting/ai
Troubleshooting guide for diagnosing and improving AI inference performance in Zylon.
## Slow Inference Performance
When experiencing slow inference times, first establish a performance baseline.
Use the [VRAM Calculator](https://apxml.com/tools/vram-calculator) to determine your GPU's expected throughput and compare it against your [model specifications](/en/v1.57/operator-manual/ai-presets/presets).
Zylon provides a benchmarking script that simulates concurrent inference requests to measure Time To First Token (TTFT), latency, and throughput. This can help identify if performance is below expectations and whether it degrades under load.
Zylon allocates compute resources to maintain consistent response times under concurrent load (8-10 simultaneous users). This means single-inference benchmarks may show lower tokens/s than the hardware's theoretical maximum, but real-world performance with multiple users will meet or exceed expectations.
```python theme={null}
import asyncio
import json
import random
import time
from dataclasses import dataclass
from typing import Optional
BASE_URL = "https:///api/gpt"
BEARER_TOKEN = "your_token_here"
MODEL = "qwen-3-5-35b-a3b"
MAX_TOKENS = 4096
PROMPT = "Write a paragraph about artificial intelligence."
CONCURRENCY_LEVELS = [1, 4, 8, 16, 32]
DEBUG = False
JITTER_MAX_MS = 200
@dataclass
class RequestResult:
success: bool
ttft: Optional[float] = None
latency: float = 0.0
generation_time: float = 0.0
tokens: int = 0
throughput: float = 0.0
error: Optional[str] = None
@dataclass
class BenchmarkStatistics:
success_rate: float
avg_ttft: float
avg_latency: float
avg_generation_time: float
avg_throughput: float
p50_ttft: float
p95_ttft: float
p99_ttft: float
@dataclass
class ConnectionConfig:
host: str
port: int
use_ssl: bool
path: str
def debug_log(message: str, force: bool = False) -> None:
if DEBUG or force:
timestamp = time.strftime("%H:%M:%S", time.localtime())
print(f"[DEBUG {timestamp}] {message}")
def parse_url(url: str) -> ConnectionConfig:
use_ssl = url.startswith("https")
host_and_path = url.split("//")[1]
parts = host_and_path.split("/", 1)
host = parts[0]
path = "/" + parts[1] if len(parts) > 1 else "/"
port = 443 if use_ssl else 80
return ConnectionConfig(host=host, port=port, use_ssl=use_ssl, path=path)
def build_http_request(
config: ConnectionConfig, payload: dict[str, object], bearer_token: str
) -> bytes:
path = config.path + "/v1/messages"
body = json.dumps(payload)
request_lines = [
f"POST {path} HTTP/1.1",
f"Host: {config.host}",
"Content-Type: application/json",
f"Authorization: Bearer {bearer_token}",
f"Content-Length: {len(body)}",
"Connection: close",
"",
body,
]
return "\r\n".join(request_lines).encode()
async def read_stream_response(
reader: asyncio.StreamReader, session_id: int, start_time: float
) -> tuple[Optional[float], Optional[float], int, int]:
ttft: Optional[float] = None
content_block_stop_time: Optional[float] = None
output_tokens = 0
event_count = 0
headers_done = False
buffer = b""
while True:
chunk = await reader.read(8192)
if not chunk:
break
buffer += chunk
if not headers_done:
if b"\r\n\r\n" in buffer:
headers_done = True
buffer = buffer.split(b"\r\n\r\n", 1)[1]
if headers_done:
lines = buffer.split(b"\n")
buffer = lines[-1]
for line in lines[:-1]:
line_str = line.decode("utf-8").strip()
if not line_str or not line_str.startswith("data: "):
continue
data_str = line_str[6:]
if data_str == "[DONE]":
debug_log(f"Session {session_id}: Stream complete")
continue
try:
event = json.loads(data_str)
event_count += 1
if ttft is None and event.get("type") == "content_block_delta":
ttft = time.perf_counter() - start_time
debug_log(f"Session {session_id}: TTFT = {ttft:.3f}s")
if event.get("type") == "content_block_stop":
content_block_stop_time = time.perf_counter()
debug_log(
f"Session {session_id}: Content block stopped at {content_block_stop_time - start_time:.3f}s"
)
if event.get("type") == "message_delta":
usage = event.get("usage", {})
output_tokens = usage.get("output_tokens", 0)
debug_log(
f"Session {session_id}: Received usage data - {output_tokens} tokens"
)
except json.JSONDecodeError as e:
debug_log(f"Session {session_id}: JSON decode error - {e}")
continue
return ttft, content_block_stop_time, output_tokens, event_count
async def make_request(session_id: int) -> RequestResult:
jitter = random.randint(0, JITTER_MAX_MS) / 1000.0
debug_log(f"Session {session_id}: Waiting {jitter:.3f}s before starting")
await asyncio.sleep(jitter)
debug_log(f"Session {session_id}: Starting request")
payload: dict[str, object] = {
"model": MODEL,
"max_tokens": MAX_TOKENS,
"messages": [{"role": "user", "content": PROMPT}],
"stream": True,
"correlation_id": f"session-{session_id}",
}
start_time = time.perf_counter()
try:
debug_log(f"Session {session_id}: Opening connection")
config = parse_url(BASE_URL)
reader, writer = await asyncio.open_connection(
config.host, config.port, ssl=config.use_ssl
)
request_bytes = build_http_request(config, payload, BEARER_TOKEN)
writer.write(request_bytes)
await writer.drain()
debug_log(f"Session {session_id}: Connection established")
ttft, content_block_stop_time, output_tokens, event_count = (
await read_stream_response(reader, session_id, start_time)
)
writer.close()
await writer.wait_closed()
end_time = time.perf_counter()
total_latency = end_time - start_time
generation_time = 0.0
throughput = 0.0
if ttft is not None and content_block_stop_time is not None:
generation_time = content_block_stop_time - (start_time + ttft)
if generation_time > 0:
throughput = output_tokens / generation_time
debug_log(
f"Session {session_id}: Completed - "
f"Latency: {total_latency:.3f}s, "
f"Generation: {generation_time:.3f}s, "
f"Tokens: {output_tokens}, "
f"Events: {event_count}, "
f"Throughput: {throughput:.2f} tok/s"
)
return RequestResult(
success=True,
ttft=ttft,
latency=total_latency,
generation_time=generation_time,
tokens=output_tokens,
throughput=throughput,
)
except Exception as e:
debug_log(f"Session {session_id}: Error - {type(e).__name__}: {e}")
return RequestResult(success=False, error=str(e))
async def run_concurrent_requests(num_users: int) -> list[RequestResult]:
debug_log(f"Starting {num_users} concurrent requests")
tasks = [make_request(i) for i in range(num_users)]
results = await asyncio.gather(*tasks)
debug_log(f"All {num_users} requests completed")
return list(results)
def calculate_percentile(data: list[float], p: float) -> float:
if not data:
return 0.0
k = (len(data) - 1) * p
f = int(k)
c = f + 1
if c >= len(data):
return data[f]
return data[f] + (k - f) * (data[c] - data[f])
def calculate_statistics(results: list[RequestResult]) -> BenchmarkStatistics:
successful = [r for r in results if r.success]
debug_log(
f"Calculating statistics for {len(successful)}/{len(results)} successful requests"
)
if not successful:
debug_log("No successful requests to calculate statistics")
return BenchmarkStatistics(
success_rate=0.0,
avg_ttft=0.0,
avg_latency=0.0,
avg_generation_time=0.0,
avg_throughput=0.0,
p50_ttft=0.0,
p95_ttft=0.0,
p99_ttft=0.0,
)
ttfts = sorted([r.ttft for r in successful if r.ttft is not None])
latencies = [r.latency for r in successful]
generation_times = [r.generation_time for r in successful]
throughputs = [r.throughput for r in successful if r.throughput > 0]
return BenchmarkStatistics(
success_rate=len(successful) / len(results),
avg_ttft=sum(ttfts) / len(ttfts) if ttfts else 0.0,
avg_latency=sum(latencies) / len(latencies),
avg_generation_time=sum(generation_times) / len(generation_times)
if generation_times
else 0.0,
avg_throughput=sum(throughputs) / len(throughputs) if throughputs else 0.0,
p50_ttft=calculate_percentile(ttfts, 0.5) if ttfts else 0.0,
p95_ttft=calculate_percentile(ttfts, 0.95) if ttfts else 0.0,
p99_ttft=calculate_percentile(ttfts, 0.99) if ttfts else 0.0,
)
def print_statistics(concurrency: int, stats: BenchmarkStatistics) -> None:
print(f"\nTesting with {concurrency} concurrent inferences...")
print(f" Success Rate: {stats.success_rate:.2%}")
print(f" Avg TTFT: {stats.avg_ttft:.3f}s")
print(f" P50 TTFT: {stats.p50_ttft:.3f}s")
print(f" P95 TTFT: {stats.p95_ttft:.3f}s")
print(f" P99 TTFT: {stats.p99_ttft:.3f}s")
print(f" Avg Latency: {stats.avg_latency:.3f}s")
print(f" Avg Generation Time: {stats.avg_generation_time:.3f}s")
print(f" Avg Throughput: {stats.avg_throughput:.2f} tok/s")
async def benchmark() -> None:
print(f"Benchmarking API: {BASE_URL}")
print(f"Model: {MODEL}")
print(f"Prompt: {PROMPT[:50]}...")
print("-" * 80)
for concurrency in CONCURRENCY_LEVELS:
debug_log(f"Starting concurrency level: {concurrency}")
results = await run_concurrent_requests(concurrency)
stats = calculate_statistics(results)
print_statistics(concurrency, stats)
if __name__ == "__main__":
asyncio.run(benchmark())
```
Update `BASE_URL`, `BEARER_TOKEN`, and `MODEL` in the script, then run it to measure TTFT, throughput, and latency under different concurrency levels. Compare your results against the theoretical maximum from the VRAM calculator to identify if performance is below expectations.
# Exporting Logs
Source: https://docs.zylon.ai/en/v1.57/operator-manual/troubleshooting/exporting-logs
This guide helps you export accurate logs so customer support can resolve issues faster and with fewer back-and-forths. Because Zylon runs locally on your infrastructure and is often deployed in fully air-gapped environments, these logs are the safest and most reliable way for us to understand what happened without accessing your data directly.
## Before you start
1. Open the Zylon app in your browser.
2. Go to the page where the problem happens.
3. Keep this tab open while you follow the steps below.
## Frontend logs (browser responses)
There are two ways to share frontend logs. You can send a full network HAR file, or you can share a single response from the request list.
A HAR (HTTP Archive) is a file that contains all network requests and responses for a page. This can speed up troubleshooting. If you want to share only a specific response, follow the single‑log steps below.
### Google Chrome
1. Open Developer Tools.
2. Press `F12` on Windows or `Cmd + Option + I` on Mac.
3. Click the `Network` tab.
4. Check `Preserve log` so requests do not disappear when the page reloads.
5. Reproduce the problem (click the same buttons or run the same action).
6. To export a HAR: right‑click anywhere in the request list and choose `Save all as HAR with content`, then share the file with support.
7. In the list of requests, click the one that matches the action you just did.
8. In the right panel, open the `Response` tab.
9. Right-click inside the response and choose `Copy`.
10. Paste the response into a text file and share it with support.
### Microsoft Edge
1. Open Developer Tools.
2. Press `F12` on Windows or `Cmd + Option + I` on Mac.
3. Click the `Network` tab.
4. Check `Preserve log` so requests do not disappear when the page reloads.
5. Reproduce the problem (click the same buttons or run the same action).
6. To export a HAR: right‑click anywhere in the request list and choose `Save all as HAR with content`, then share the file with support.
7. In the list of requests, click the one that matches the action you just did.
8. In the right panel, open the `Response` tab.
9. Right-click inside the response and choose `Copy`.
10. Paste the response into a text file and share it with support.
### Mozilla Firefox
1. Open Developer Tools.
2. Press `F12` on Windows or `Cmd + Option + I` on Mac.
3. Click the `Network` tab.
4. Reproduce the problem (click the same buttons or run the same action).
5. To export a HAR: right‑click anywhere in the request list and choose `Save All As HAR`, then share the file with support.
6. In the list of requests, click the one that matches the action you just did.
7. In the right panel, open the `Response` tab.
8. Right-click inside the response and choose `Copy`.
9. Paste the response into a text file and share it with support.
If you cannot find the request, try these quick checks.
1. Make sure the `Network` tab is selected.
2. Reload the page and repeat the action.
3. Look for filters like `Fetch/XHR` and select them.
## Non-frontend logs (backend, AI, and other services)
Logs for non-frontend issues must be retrieved from the relevant pod instance (backend, AI services, or other components). Check your pods to find the correct service before collecting logs.
See the [system admin dashboard guide for pod status and service visibility](/en/v1.57/operator-manual/operations/sys-admin-dashboard)
# Nvidia Drivers
Source: https://docs.zylon.ai/en/v1.57/operator-manual/troubleshooting/nvidia-drivers
This troubleshooting sections provides solutions to common issues encountered with Nvidia drivers on Zylon installations.
### Why you might encounter issues with Nvidia drivers
In order to provide latest GPU capabilities for Zylon we usually require the latest versions of the Nvidia drivers installed, which means they have to be compiled on demand for your specific kernel version your hardware is running.
At the same time, open source Nvidia drivers are still under active development and sometimes issues may arise during installation or runtime.
In particular, during kernel updates or changes to the system configuration, Nvidia drivers may stop working properly, failing to detect the GPU or causing the AI services to malfunction due to memory usage discrepancies.
Here are some common ways to diagnose if that is the case and how to fix it.
### 1 - Check the Zylon Status page
Navigate to the Zylon Status page at `https:///status`. Check for any error in the AI Service section and in particular `zylon-triton`.
If the service is not online, continue with the next steps to diagnose the issue.
If the system is online but Zylon is still failing, the source is most likely and application-level issue, please contact Zylon support.
If you can't access the status page, skip to step 2.
### 2 - Verify Nvidia Driver Status
Check `nvidia-smi` output:
```bash theme={null}
nvidia-smi
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 575.51.03 Driver Version: 575.51.03 CUDA Version: 12.9 |
|-----------------------------------------+------------------------+----------------------+
| GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC |
| Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. |
| | | MIG M. |
|=========================================+========================+======================|
| 0 NVIDIA L40S Off | 00000000:30:00.0 Off | 0 |
| N/A 38C P0 104W / 350W | 40673MiB / 46068MiB | 0% Default |
| | | N/A |
+-----------------------------------------+------------------------+----------------------+
+-----------------------------------------------------------------------------------------+
| Processes: |
| GPU GI CI PID Type Process name GPU Memory |
| ID ID Usage |
|=========================================================================================|
| 0 N/A N/A 18592 C tritonserver 490MiB |
| 0 N/A N/A 23968 C VLLM::EngineCore 38968MiB |
| 0 N/A N/A 26834 C VLLM::EngineCore 1196MiB |
+-----------------------------------------------------------------------------------------+
```
It should report the GPU status, along with the process using it.
#### 2.1 - Drivers not working: nvidia-smi can't communicate with the NVIDIA driver
This is the most common error, usually caused by a kernel update during an unattended upgrade. The fix requires
Run the following commands:
```bash theme={null}
sudo zylon-cli install-drivers --force # Reinstall Nvidia drivers
helm uninstall gpu-operator -n nvidia # Uninstall GPU operator
sudo reboot # Reboot the system to clear any cached GPU info
sudo zylon-cli sync # Reinstall GPU operator when the system is back online
```
Wait a few minutes and check the status page again, the issue should be resolved. The driver installation will take 10 to 15 minutnes, and additional 3\~5 minutes until Triton comes back online.
#### 2.2 - Drivers working: nvidia-smi is working properly but Triton service still failing
If `nvidia-smi` is working properly but the Triton service is failing (confirm this in the status page), this is usually caused by caching issues regarding GPU autodetection, to fix it run:
```bash theme={null}
helm uninstall gpu-operator -n nvidia
sudo reboot # Reboot the to clear any cached GPU info
sudo zylon-cli sync # Reinstall GPU operator
```
Wait a few minutes and check the status page again, the issue should be resolved. Note that in this case Triton might take 3\~5 minutes to come back online.
#### 2.3 - Drivers working, but fixes for 2.1 and 2.2 did not work
If `nvidia-smi` is working but the previous fixes did not work, the issue might be located in the Nvidia Container Toolkit installation.
Verify the file located here: `/etc/k0s/containerd.d/nvidia.toml` exists, and has the following content:
```toml theme={null}
# Allow k0s containerd to use nvidia-container-runtime
[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.nvidia]
privileged_without_host_devices = false
runtime_engine = ""
runtime_root = ""
runtime_type = "io.containerd.runc.v2"
[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.nvidia.options]
BinaryName = "/usr/bin/nvidia-container-runtime"
```
If the file is missing, you can automatically recreate it by running:
```bash theme={null}
sudo zylon-cli install
sudo reboot # Reboot the system
```
Wait a few minutes and check the status page again, the issue should be resolved.
# General issues
Source: https://docs.zylon.ai/en/v1.57/operator-manual/troubleshooting/troubleshoot
Zylon troubleshooting is mostly done through the `zylon-cli` command line tool.
## Zylon Doctor
`zylon-cli` comes with a built in diagnosis tool.
Run:
```bash theme={null}
sudo zylon-cli doctor
```
to get all the relevant information for debugging. The output of the command will guide your further in case you need more detailed information in case some part of the system is failing.
## Change Server IP after Zylon has been installed
In case you need to move the server where Zylon is installed to a different IP address, there is a change that needs to be done.
1. Stop the K0s cluster: `sudo k0s stop`
2. Edit the file `/var/lib/k0s/kubelet.conf` and replace the old IP for the new IP
3. Reboot the machine
4. Run `sudo zylon-cli sync-kube-config`
## Debugging tools
In addition to the doctor command, additional debugging tools can be enabled in `zylon-conf.yaml`.
Be aware that these tools tap directly into Zylon internals and you can break the system if you modify any critical resource.
### Background task debugging
Enable the background task debug tool by adding these lines to the configuration:
```yaml theme={null}
zylonGPTWorker:
exposeIngress: true
# flowerPassword: "zylon-flower"
# you can customize the password if you want to expose it permanently
```
After the update, a new endpoint will be available under `/gpt-worker/tasks` that contains information about the running operations. The technology powering the dashboard is [flower](https://flower.readthedocs.io/en/latest/).
Username is `flower` and default password is `zylon-flower`
### Kubernetes dashboard
Enable kubernetes admin dashboard for advanced Zylon control by adding these lines to the configuration:
```yaml theme={null}
adminDashboard:
enabled: true
exposeIngress: true
```
After the update, a new endpoint will be available under `/kube-dashboard`. The technology powering dashboard is [kubernetes dashboard](https://kubernetes.io/docs/tasks/access-application-cluster/web-ui-dashboard/).
In order to connect to the dashboard you must generate a token by running the following command in your instance
```yaml theme={null}
kubectl create token -n zylon zylon
```
This token gives FULL ACCESS to all Zylon resources, configuration, secrets, and so on.
> As a general rule, once you are doing using the dashboard you should disable it due to security risks.
## Improve indexing for versions before 1.13.0
If you are installing a Zylon version greater than 1.13.0 (Release on Jan 27th 2025) skip this section, it only applies to previous versions.
With the release v1.13.0 and support for bigger files indexing is required for better performance. This is a one time operation that will create the index in the vector database for your existing and new documents.
Simply run the script in the machine where Zylon is installed. Running the script multiple times has no negative effect. Indexing time might vary depending on the number of documents, but should be faster than a minute.
* Indexing script
```bash theme={null}
#!/bin/bash
# Configuration
QDRANT_HOST="localhost"
QDRANT_PORT="6333"
MAX_RETRIES=30
RETRY_INTERVAL=2
QDRANT_RELEASE_NAME="zylon"
NAMESPACE="$QDRANT_RELEASE_NAME"
# Cleanup function
cleanup() {
echo "Cleaning up..."
if [ ! -z "$PORT_FORWARD_PID" ]; then
echo "Stopping port-forward process..."
kill $PORT_FORWARD_PID 2>/dev/null
wait $PORT_FORWARD_PID 2>/dev/null
fi
exit 0
}
# Set up trap for cleanup
trap cleanup SIGINT SIGTERM EXIT
# Start port-forwarding
echo "Starting port-forwarding..."
kubectl port-forward "svc/${QDRANT_RELEASE_NAME}-qdrant" -n "$NAMESPACE" "${QDRANT_PORT}:6333" &
PORT_FORWARD_PID=$!
# Verify port-forward process started successfully
if ! ps -p $PORT_FORWARD_PID > /dev/null; then
echo "Error: Failed to start port-forwarding"
exit 1
fi
echo "Port-forwarding started with PID $PORT_FORWARD_PID"
# Function to check if Qdrant is ready
check_qdrant_health() {
curl --silent --fail "http://${QDRANT_HOST}:${QDRANT_PORT}/healthz" > /dev/null
return $?
}
# Wait for Qdrant to be ready
echo "Waiting for Qdrant to be ready..."
retries=0
until check_qdrant_health; do
# Check if port-forward is still running
if ! ps -p $PORT_FORWARD_PID > /dev/null; then
echo "Error: Port-forward process died"
exit 1
fi
retries=$((retries + 1))
if [ $retries -eq $MAX_RETRIES ]; then
echo "Error: Qdrant service did not become ready in time"
exit 1
fi
echo "Qdrant is not ready yet. Retry $retries/$MAX_RETRIES..."
sleep $RETRY_INTERVAL
done
echo "Qdrant is ready! Creating indexes..."
# Create artifact_id index
echo "Creating artifact_id index..."
curl -X PUT "http://${QDRANT_HOST}:${QDRANT_PORT}/collections/zgptvector/index" \
-H 'Content-Type: application/json' \
-d '{
"field_name": "artifact_id",
"field_schema": {
"type": "keyword",
"on_disk": true
}
}' || exit 1
# Check if the first request was successful
if [ $? -ne 0 ]; then
echo "Error: Failed to create artifact_id index"
exit 1
fi
# Create project_id index
echo "Creating project_id index..."
curl -X PUT "http://${QDRANT_HOST}:${QDRANT_PORT}/collections/zgptvector/index" \
-H 'Content-Type: application/json' \
-d '{
"field_name": "project_id",
"field_schema": {
"type": "keyword",
"on_disk": true
}
}' || exit 1
# Check if the second request was successful
if [ $? -ne 0 ]; then
echo "Error: Failed to create project_id index"
exit 1
fi
echo "Successfully created all indexes!"
```
## OpenEBS is not working, making PODs be Pending
In certain situations, while Zylon is being installed, it may cause OpenEBS to not install correctly. To remedy this, you can do the following:
```bash theme={null}
kubectl delete pods,deployments,statefulsets,daemonsets,pv,pvc,sc --all -n zylon
kubectl delete namespace openebs
helm uninstall openebs -n openebs
sudo zylon-cli sync
```