Tiqora
Tiqora is a modern, self-hosted ticket / helpdesk system that is
database-compatible with OTRS 6.0.x and Znuny 6.0–7.3 (MariaDB/MySQL and
PostgreSQL). It is a clean-room reimplementation (Python FastAPI + React), not a
fork of Znuny — no Znuny source code is included or redistributed.
| |
|---|
| Backend | Python 3.12+, FastAPI, SQLAlchemy 2 async, Alembic, Pydantic v2 |
| Frontend | React + TypeScript + Vite, Tailwind, theming via CSS variables |
| Search | Meilisearch (full-text; hybrid / vector RAG planned later) |
| Jobs | Plain asyncio worker loops (tiqora-worker, tiqora-ai-worker), Redis for sessions/pub-sub |
| AI surface | MCP server (FastMCP) under the same permission engine as UI/REST |
| License | AGPL-3.0 — Copyright © 2026 Cygnus Networks GmbH |
Try it
In the browser, nothing to install: the interactive demo
runs the full agent, admin and portal UI against mock data.
On your machine, one command (Docker with Compose v2):
curl -fsSLO https://raw.githubusercontent.com/CygnusNetworks/tiqora/main/docker-compose.quickstart.yml
docker compose -f docker-compose.quickstart.yml up -d
Open http://localhost:8000/ and sign in as root@localhost / tiqora-demo. The first
start creates the database and seeds 40 fake tickets; docker compose -f docker-compose.quickstart.yml down -v removes everything again. The quickstart is for
evaluation only (fixed passwords, plain HTTP). For a real installation see
Getting started.
Running OTRS or Znuny already? Tiqora can work on your existing database, next to
Znuny — read Moving off OTRS/Znuny without a big-bang migration
or the comparison with Znuny, OTRS, Zammad and others.
Questions, ideas, war stories from your OTRS migration:
GitHub Discussions.
Why Tiqora
- Modern web UI — agent workspace, admin console, and customer portal that feel
like a current product, not a 2000s helpdesk skin.
- Znuny / OTRS 6.0–7.3 database compatibility — same core ticket tables; a
runtime schema profile detects the peer (see
docs/support-matrix.md). Parallel operation on
one shared database is a first-class path (additive
tiqora_* tables only until
you explicitly take schema ownership). Preferred peers: Znuny 6.5 (LTS) or
7.3.
- AI-ready ticket search — Meilisearch indexing plus an MCP server so AI agents
act with the same ACLs as humans.
- AI agent assistance — per-queue policies drive draft replies, state-only
ticket summaries (document- and attachment-aware), AI triage (queue routing
for new tickets), text refine with a word-level diff to review (and a
call-note mode for phone notes), and an optional autonomous auto-reply worker.
Attachments get text extraction plus a vision pre-pass for images; sensitive
data is PII-masked (spaCy NER) before any LLM call; every request lands in an
audit log with per-subject ACLs, token/request limits and per-provider cost
budgets (day/week/month). Every AI-written article is marked 🤖 in the ticket
and carries the tool trace behind it — each call with the arguments it was
made with. The agent can hand off to a human, which really stops the
auto-reply until someone takes over, and agents can pause all automatic AI
actions per ticket. Bring your own OpenAI-compatible endpoints: a model
catalog with fallback profiles and per-task routing (research, answer,
triage, summary, refine, vision — globally or per queue). Gated by the operation
mode so nothing autonomous runs during parallel operation (except auto-replies on
Tiqora-only channels such as Telegram).
- PGP and S/MIME — Znuny-compatible key stores shared with a running Znuny;
inbound mail verified and decrypted (security badge per article), outbound
replies, forwards, new email tickets and event notifications signed and/or
encrypted, with per-queue defaults (sign by default; encryption off / when
possible / required), customer keys, and settings editable in the admin UI
(Znuny's SysConfig still wins where it is set).
- — a messenger-style chat composer for Telegram
tickets (attachments, quote replies, answer buttons that resolve the ticket,
edit/retract, chat snippets), and Znuny phone parity with an incoming-call
popup fed by a PBX webhook, caller lookup, click-to-call and a compact phone
ticket form.
Live product site & demo
Product site — overview, features, screenshots.
Interactive demo — full agent, admin, and
portal UI in the browser against mock data (nothing is saved). Built from frontend/
with Mock Service Worker; local build:
VITE_BASE=/tiqora/demo/ pnpm --filter tiqora-frontend build:demo
Screenshots
Inbox sorted by last activity, with e-mail / Telegram / phone filters — and a CTI popup for the call that is ringing through.
Grouped by topic; click a section to expand it, click a picture for full size. The
product site shows the same set as a gallery with a light/dark switch.
| Ticket summary | Draft grounded in MCP tools | Auto-reply with its tool trace |
|---|
| | |
| Refine, reviewed as a diff | Model catalog | Task → profile routing |
| | |
| Per-queue policies | AI settings | Providers |
| | |
| Cost budget & tool rounds | MCP tool sources | LLM request audit |
| | |
| Inbox | Ticket view | Dashboard |
|---|
| | |
| Search | Reporting & SLA | Calendar |
| | |
| Knowledge base | | |
| | |
| Dashboard with filters | Incident in the ticket view | CI detail |
|---|
| | |
| CMDB list | CI with versions and links | Impact graph |
| | |
| CMDB class designer | ITSM administration | |
| | |
| Telegram chat | CTI call popup | Phone ticket with caller lookup |
|---|
| | |
| Verified signature on arrival | Sign & encrypt in the composer | Per-queue security defaults |
|---|
| | |
| PGP keys | S/MIME certificates | |
| | |
| Queues | Escalation matrix | Agents |
|---|
| | |
| Groups | Roles ↔ groups | Customer users |
| | |
| Customer user groups | Dynamic fields | Privacy / GDPR |
| | |
| Two-factor | | |
| | |
| Login | Account security | Account menu | Customer portal |
|---|
| | | |
Generated with SCREENSHOTS=1 pnpm exec playwright test screenshots
(e2e/fixtures/rich-mock.ts) — no backend required. Use THEME=dark / LANG_UI=de for variants.
Also included
| Area | Notes |
|---|
| Ticket write path + Znuny invariants | Golden-master multi-peer matrix (OTRS/Znuny 6.0–7.3) |
| GenericInterface compatibility | Provider: Session*, TicketCreate/Update/Get/Search/HistoryGet, TimeAccountingGet, OutOfOffice, ConfigItemGet/Search/Create/Update/Delete (depending on the ITSM mode); REST + SOAP. Requester: invokers on ticket events with retries, conditions, response actions and a debugger, ExecuteInvoker process action — docs/compatibility.md, docs/guide/webservices.md |
| MCP tools | ticket_*, customer lookup, KB, read-only CMDB (cmdb_search, cmdb_get, cmdb_impact), plus tools from plugins — see docs/api/mcp.md, docs/ai-integration.md |
| AI assistance subsystem | Draft replies, summaries, triage, refine (diff review, call notes), auto-reply worker, human handoff, per-ticket pause, 🤖 origin traces, attachment/vision, PII masking, model catalog/profiles/task routing, per-subject ACL, cost budgets & audit — /admin/ai/*, docs/ai-integration.md |
| Daemon takeover (mail, escalation, notify, GA) | Per-function flags, off by default |
| Calendar / appointments | Month/week/agenda UI; reuses Znuny calendar* tables |
| Process management (BPM) and process designer | Reuses Znuny pm_* tables; visual designer (canvas, validation, Znuny YAML import/export, versions), deploy through TiqoraSync while Znuny runs — docs/process-management.md |
| PGP / S-MIME |
Architecture overview
┌──────────────────────────────────────────┐
│ Clients │
│ Agent UI · Portal · Admin · AI agents │
└───────────┬──────────────┬────────────────┘
│ │
/api/v1 │ │ MCP (streamable HTTP)
/znuny-compat/* │ │
▼ ▼
┌────────────────┐ ┌─────────────┐
│ tiqora-api │ │ tiqora-mcp │
│ (FastAPI) │ │ (FastMCP) │
└───────┬────────┘ └──────┬──────┘
│ │
│ domain/* │
│ permissions/* │
▼ ▼
┌─────────────────────────────────────────────┐
│ Shared domain layer │
│ TicketService · ACL · sessions · outbox │
└───────────┬───────────────────┬─────────────┘
│ │
┌──────────────▼──────┐ ┌────────▼────────┐
│ OTRS/Znuny tables │ │ tiqora_* tables│
│ (6.0–7.3; R/W, no │ │ (Alembic chain │
│ schema changes) │ │ versions_tiqora)│
└──────────┬──────────┘ └────────┬────────┘
│ │
┌────────────▼──────────┐ │
│ Peer instance │ │
│ (optional parallel) │◄── cache invalidation via TiqoraSync OPM
└───────────────────────┘
│
┌────────────▼────────────────────────────────────┐
│ tiqora-worker · ai-worker · Redis · Meili │
└─────────────────────────────────────────────────┘
flowchart TB
subgraph clients [Clients]
AgentUI[Agent UI]
Portal[Customer Portal]
Admin[Admin]
AI[AI Agents via MCP]
end
subgraph tiqora [Tiqora]
API[tiqora-api FastAPI]
MCP[tiqora-mcp FastMCP]
Worker[tiqora-worker + ai-worker]
Domain[domain + permissions]
end
subgraph data [Shared data plane]
ZTables[(Znuny tables)]
TTables[(tiqora_* tables)]
Redis[(Redis)]
Meili[(Meilisearch)]
end
Znuny[OTRS/Znuny 6.0–7.3 peer]
AgentUI --> API
Portal --> API
Admin --> API
AI --> MCP
API --> Domain
MCP --> Domain
Domain --> ZTables
Domain --> TTables
Worker --> ZTables
Worker --> TTables
Worker --> Redis
Worker --> Meili
Znuny --> ZTables
Domain -.->|tiqora_cache_invalidation| Znuny
Package layout (backend):
backend/src/tiqora/
db/legacy/ # Hand-written models for Znuny tables + conformance tests
db/tiqora/ # tiqora_* models (Alembic: versions_tiqora / versions_owned)
znuny/ # Invariants: ticket numbers, history, escalation, follow-up, …
domain/ # Services — sole write paths, bundling invariants
permissions/ # Groups/roles + ACL for UI, REST, MCP
events/ # Async bus + transactional outbox
channels/ # Channel plugins (email, SMS, WhatsApp, Telegram, phone)
storage/ # StorageBackend interface (DB MIME in V1)
api/ # v1 routers + GenericInterface compat layer
mcp_server/ # FastMCP process
worker/ # asyncio worker loops (daemon takeover, outbox, pollers)
kb/ # Knowledge base
Parallel operation with Znuny
Tiqora and Znuny can share one PostgreSQL or MariaDB/MySQL database:
| Rule | Detail |
|---|
| No Znuny schema changes | Tiqora never alters Znuny tables until post-cutover ownership mode |
New tables only as tiqora_* | Alembic chain versions_tiqora/ |
| Behavioural parity | Ticket numbers, history formats, escalation columns, search flags must match Znuny |
| Daemon ownership | Znuny keeps mail/escalation/notifications/GenericAgent until feature flags hand each over |
| Cache coherence | Optional TiqoraSync Znuny OPM reads tiqora_cache_invalidation; or lower Znuny cache TTLs |
See docs/parallel-operation.md for the full invariant list.
Getting started — three ways to run
Quick start (development)
Prerequisites
- Docker / Docker Compose
- uv (Python)
- Node 20+ and pnpm (frontend)
- Optional: just
1. Start infrastructure
docker compose -f docker-compose.dev.yml up -d
# MariaDB :3306, Postgres :5432, Redis :6379, Meilisearch :7700, Mailpit :8025/:1025
2. Backend
cd backend
uv sync
export DATABASE_URL=postgresql+asyncpg://tiqora:tiqora@localhost:5432/tiqora
# or: mysql+aiomysql://tiqora:tiqora@localhost:3306/tiqora
export REDIS_URL=redis://localhost:6379/0
export MEILI_URL=http://localhost:7700
uv run uvicorn tiqora.api.app:create_app --factory --reload --host 0.0.0.0 --port 8000
Health checks:
curl -s http://localhost:8000/health
curl -s http://localhost:8000/ready
curl -s http://localhost:8000/metrics | head
3. Frontend
cd frontend
pnpm install
pnpm dev
# http://localhost:5173 — agent, portal, and admin UI
Makefile / just shortcuts
make dev-up # or: just dev-up
make sync
make api
make test
make lint
Toggling the customer portal
The customer portal is off by default: /api/portal/* answers 404 and /, /portal,
and /portal/login all redirect to the agent login. Two switches control it:
- At deployment level,
TIQORA_PORTAL_ENABLED=true enables it. Without it the portal is
hard-off and the admin switch cannot override that; the UI control is disabled, and a
write attempt against the API returns 409.
- In the admin UI (only once the env var is set), on the Authentication / 2FA page →
"Customer portal available". Takes effect immediately: turning it off makes the portal
API answer 404, stops running customer sessions, and sends the start page to the agent
login.
Customer records, customer companies, and email tickets are unaffected either way. The
Znuny-compat GenericInterface (/znuny-compat/*) is also unaffected — it's an integration
API, not part of the portal, so customers with credentials can still reach their own
tickets through it while the portal is off.
Tech stack
| Layer | Choice | Rationale |
|---|
| API | FastAPI + Pydantic v2 | Async-native, OpenAPI-first |
| ORM | SQLAlchemy 2 async | Dual drivers: asyncpg + aiomysql |
| Migrations | Alembic (two chains) | Own tables now; owned Znuny schema only after cutover |
| Jobs | Plain asyncio loops | Feature-flagged daemon takeover without an extra task queue; AI in its own worker |
| Search | Meilisearch | Fast full-text; later hybrid/vector for RAG |
| Sessions | Redis server-side | No JWT; Znuny-compatible session table for compat API |
| Frontend | Vite, React, TS, Tailwind | One app, three route trees, code-split |
| i18n | react-i18next | 49 locales (Znuny catalogue parity; docs/i18n.md) |
| Observability | structlog JSON, Prometheus /metrics | Zabbix template placeholder under deploy/zabbix/ |
| MCP | FastMCP (separate process) | Same permission engine as UI/REST |
Browser floor: the UI's theme tokens are CSS variables tinted with
color-mix(), so it needs Chrome/Edge 111+, Safari 16.4+, or Firefox 113+
(all shipped in 2023). Older browsers render an uncoloured, but still usable,
approximation.
Status
Core functionality is implemented and covered by automated tests, including
schema-matrix (Layer A) and multi-peer golden-master (Layer B) checks for
OTRS/Znuny 6.0–7.3. Schema ownership defaults off and requires an
explicit operator action — see docs/cutover.md.
Znuny feature parity
Day-to-day agent, customer-portal and admin work is covered, and since v0.18.0 / v0.19.0
also what used to be on the gap list: saved searches, widget dashboards, the statistics
framework (builder, import, schedules), the process designer, the GenericInterface
requester, SAML, web chat, ITSM / CMDB and a plugin system as the replacement for Perl OPM
add-ons. The maintained, detailed list with every status (and what is only partial) is
docs/compatibility.md. Still
not implemented:
| Znuny feature | Status |
|---|
| Admin screens: sessions, SQL box, maintenance windows, system log | missing |
| Calendar admin and ticket appointment rules (queue/SLA) | missing |
| Customer portal print view | missing |
Follow-up as a new ticket (queue.follow_up_id == 3) | missing (behaves like reopen) |
| Process transitions after every ticket change | missing (evaluated after process dialogs and new process tickets) |
| ITSM change management (changes, work orders), service catalogue, approvals | planned (wave 5) |
| SysConfig edit/deploy UI | by design (settings are read from sysconfig_*) |
| Perl OPM packages / Package Manager | by design (replaced by plugins) |
Documentation
Full index: docs/README.md
Getting started & operating
| Document | Content |
|---|
| docs/guide/znuny-to-tiqora.md | Operator playbook: run alongside Znuny, then migrate onto Tiqora |
| docs/deploy/docker-compose.md | Docker Compose deployment — services, env vars, reverse proxy |
| docs/support-matrix.md · docs/parallel-operation.md · docs/cutover.md | Peer support matrix, parallel-op invariants, cutover runbook |
| docs/development.md · docs/testing.md | Local dev, seeding/anonymizing, test suites |
| docs/guide/fresh-install.md | Greenfield install, then the optional building blocks (ITSM mode, reports, SSO, web chat, plugins) |
| docs/deployment.md | Production notes, upgrade notes per release (v0.19.0) |
Feature areas (guides marked German have an English summary block unless noted)
| Document | Content |
|---|
| docs/itsm.md · docs/cmdb.md · docs/itsm-import.md | ITSM modes, incident / problem / major incident, priority matrix, link types; CMDB; Znuny ITSM import and survey (German) |
| docs/reporting.md | Reports: catalogue, builder, saved reports, Znuny stats import, PDF, schedules |
| docs/dashboards.md | Widget dashboards, role templates, wallboards (German) |
| docs/guide/identity-providers.md | SAML, OIDC, LDAP, customer SSO, SCIM, step-up MFA (German) |
| docs/guide/webchat.md · docs/webchat.md | Web chat: administrators and agents (German, English summary); internals (English) |
| docs/plugins.md | Plugin system: admin part (German), developer guide (English) |
| docs/process-management.md · docs/guide/webservices.md |
API & integrations
Reference
Compatibility statement
- Target: OTRS 6.0.x and Znuny 6.0–7.3 database schemas (MariaDB/MySQL
and PostgreSQL). Full matrix: docs/support-matrix.md.
Preferred peers: Znuny 6.5 (LTS) or 7.3 (current release). Unknown schemas refuse to start
unless overridden (
TIQORA_ALLOW_UNKNOWN_LEGACY_SCHEMA /
TIQORA_LEGACY_SCHEMA_PROFILE=<profile_id>).
- Behaviour: Ticket numbering, history name formats, escalation columns, and
search-index flags must remain readable and writable by a co-running peer during
parallel operation (golden-validated across the multi-peer matrix).
- Code: Tiqora is an independent implementation. Local peer release trees
(
znuny-6.5.22/, znuny-7.3.5/, …) are gitignored and never published in
this repository.
Contributing
Contributions are welcome. Read CONTRIBUTING.md first, especially
the clean-room rule (never copy Znuny/OTRS source) and the rule about test data
(no real tickets, names or addresses). Questions go to GitHub Discussions;
security problems go through SECURITY.md, not public issues.
License
Tiqora is licensed under the GNU Affero General Public License v3.0
(AGPL-3.0) — see LICENSE — with three documented exceptions
(the GPL-3.0 TiqoraSync Znuny add-on, the dual-licensed
backend/src/tiqora/znuny/ compatibility modules, and the verbatim upstream
schema fixtures). See NOTICE.md for the complete licensing
picture, the reimplementation statement, and trademark notes.
Copyright © 2026 Cygnus Networks GmbH.
"Znuny" is a trademark of Znuny GmbH; "OTRS" is a registered trademark of
OTRS AG. Tiqora is not affiliated with, endorsed by, or sponsored by either
company; the names are used solely to describe factual compatibility.
