Konversio 101

First login: what to set up first

First login: what to set up firstAfter your Konversio instance is running, the interface will load but nothing useful is configured yet. This checklist walks through the setup steps in order of priority.1. Change the default passwordThe seed creates an admin account with a public default password. Change it before you do anything else, especially if your instance is accessible from the internet.Go to Profile Settings (bottom-left, your avatar) → Password. Set a strong password and update the email address to one you actually control. You will need this address for password resets.2. Update your account nameStill in Profile Settings, set your display name and upload a profile photo if you want one. Agents see each other's names throughout the interface, so readable names matter.Under Settings → Account Settings, update the account name from the default to your organisation's name. This appears in email notifications sent to contacts.3. Create your first inboxWithout an inbox, no conversations can arrive. Go to Settings → Inboxes → Add Inbox.Choose a channel type. For a quick test, Website (live chat) requires no external credentials — it gives you a JavaScript snippet you can embed anywhere, including a local HTML file. For email, you will need SMTP/IMAP credentials.Give the inbox a clear name. You can always add more inboxes later.4. Invite your first agentGo to Settings → Agents → Invite Agent. Enter their name, email address, and role (Agent or Administrator). They will receive an email invitation with a link to set their password.Once invited, assign them to the inbox you just created: Settings → Inboxes → select the inbox → Collaborators tab → add the agent.5. Set up your own profile notificationsGo to Profile Settings → Notifications. By default, you may not receive alerts for new conversations or assignments. Review which notification types you want — email, browser push, or both — and enable them.6. (Optional) Configure PilotIf you want AI-assisted responses, go to Settings → Pilot. You will need an inference endpoint — either a locally running model server or a compatible API. The Pilot documentation covers supported models (Gemma 4, Qwen) and how to point Konversio at your inference host.Pilot is optional. The platform works fully without it.7. Send a test conversationWith an inbox created, open the live chat test URL (shown in the inbox settings) or send a test email to your inbox address. Verify the conversation appears in the Conversations view and that you can reply. This confirms your setup is working end to end before you open it up to real users.What you have nowAfter completing this checklist, you have: a secure admin account, at least one working inbox, at least one agent who can log in, and a confirmed working conversation flow. That is enough to start using Konversio for real.

Key concepts

Key conceptsBefore you start configuring Konversio, it helps to understand the mental model. These are the core building blocks you will encounter throughout the interface.InboxAn inbox is a channel through which conversations arrive. Each inbox maps to one communication channel: a live chat widget, an email address, a WhatsApp number, a Telegram bot, or an API endpoint. You can have multiple inboxes — for example, one for sales chat, one for support email.Inboxes are configured separately, and agents are assigned to specific inboxes. A conversation always belongs to exactly one inbox.ConversationA conversation is a thread of messages between your team and a contact. Every inbound message that cannot be matched to an existing open conversation creates a new one. Conversations have a status: open, resolved, or pending. They can be assigned to an agent, a team, or left unassigned.ContactA contact is a person who has reached out through one or more channels. Contacts are deduplicated where possible — if the same person emails and also uses live chat, you can merge those records. Contact history shows all past conversations.AgentAn agent is a user who handles conversations. Agents log in to the interface, pick up conversations from the inbox queue, and reply to contacts. Each agent has a role: Agent or Administrator.AdministratorAdministrators can do everything agents can, plus configure the platform — create inboxes, manage agents, set up automation rules, configure integrations, and access reports.TeamA team is a group of agents. Teams are useful for routing: you can assign conversations to a team rather than a specific agent, and anyone on that team can pick it up. Typical teams: Support, Sales, Billing.LabelLabels are tags you apply to conversations. They are free-form and colour-coded. You can use them for routing logic in automation rules, for filtering views, and for reporting. Examples: urgent, bug, refund-request.Canned responseA canned response is a saved reply snippet. Agents can trigger them by typing a short code during a conversation. Useful for common answers — pricing questions, operating hours, reset instructions — where you want consistency and speed without copy-pasting.AutomationAutomation rules trigger actions when conditions are met. For example: assign all conversations tagged billing to the Billing team, or send a specific canned response when a conversation has been waiting more than two hours. Rules run automatically without agent intervention.PilotPilot is Konversio's built-in AI support agent. It can be configured to handle conversations automatically, suggest replies to agents, or summarise threads. Unlike Chatwoot's Captain, Pilot is fully open source and runs on open models with no external provider required. See the Pilot documentation for setup details.

Konversio and Chatwoot: what carries over, what changed

Konversio and Chatwoot: what carries over, what changedKonversio is a fork of Chatwoot CE v4.13, not a rewrite. If you are coming from Chatwoot, most of what you know still applies. This article covers what is identical, what changed, and how to think about whether to migrate an existing instance or start fresh.What is identicalEverything in Chatwoot CE at v4.13 carries over unchanged:Inboxes and conversations — the same channel types, the same conversation model, the same status workflowAgents, teams, and roles — identical permission structureAutomation rules — same rule builder, same trigger and action typesReports — overview, CSAT, label reports, all presentHelp Center — article-based knowledge portal, same editorCanned responses and labels — no changesSLAs — same configuration and enforcementIntegrations — Slack, Webhooks, SMTP, and the others from CE are all intactAPI — the REST API is the same; existing integrations built against Chatwoot CE should work without modificationDatabase schema — the schema is the same at the point of the fork, which is relevant for migrations (see below)If a feature existed in Chatwoot CE v4.13, it exists in Konversio.What changedCaptain is gone. Chatwoot's proprietary AI agent has been removed. If you were using Captain on a Chatwoot Cloud plan, that functionality does not carry over. Captain was never part of CE, so self-hosted CE users are not affected.Pilot is added. Konversio ships its own AI support agent, Pilot, which is MIT-licensed and runs on open models — Gemma 4, Qwen, Whisper. Pilot is not a drop-in replacement for Captain feature-by-feature; it is a different implementation with a different configuration model. Expect to set it up from scratch.License is fully MIT. Chatwoot CE was already MIT-licensed for the application code, but the broader Chatwoot project included proprietary components. Konversio is MIT throughout — no proprietary layers.Upstream divergence will grow. Konversio is a fork, not a downstream package. Bug fixes and features from Chatwoot will not automatically appear. The Konversio team will backport security fixes and may selectively pull CE improvements, but the two projects will diverge over time.Who should migrate from Chatwoot CEMigration is straightforward if you are self-hosting Chatwoot CE on v4.13. Because the database schema matches at the fork point, a database dump from Chatwoot CE v4.13 can be restored into Konversio with no schema changes required.Good reasons to migrate:You want Pilot and the fully open AI stackYou want a platform whose roadmap is focused on EU deployment and open inferenceYou do not need or want future Chatwoot Cloud featuresReasons to stay on Chatwoot CE:You are tracking Chatwoot's upstream actively and want new CE features as they shipYou have no use case for the AI layer and the fork does not add value for youWho should start freshIf you are evaluating both platforms with no existing data, start with Konversio directly. There is no meaningful setup cost difference, and you will be on the platform you intend to run long-term.SummaryAreaChatwoot CE v4.13KonversioCore platform featuresYesYes (identical)Captain AIEnterprise onlyRemovedPilot AINoYes, MIT-licensedLicenseMIT (app code)MIT throughoutUpstream syncActiveFork, selective backportsEU open inferenceNoYes

Quick start with Docker Compose

Quick start with Docker ComposeThe fastest way to run Konversio is with Docker Compose. This guide covers the minimal steps to get a working instance on a single server.PrerequisitesDocker and Docker Compose installed on your serverA server with at least 2 GB RAM (4 GB recommended if you plan to run Pilot)Ports 3000 (or 80/443 if you set up a reverse proxy) accessibleYou do not need Ruby, Node, or any other runtime installed locally. Everything runs inside containers.Step 1: Copy the environment fileClone the repository and copy the example environment file:git clone https://github.com/Konversio-Org/konversio.git cd konversio cp .env.example .env Open .env and set the values that matter for a first run. At minimum, review SECRET_KEY_BASE (generate one with openssl rand -hex 64) and the database credentials. You can leave most other values at their defaults for a local test.Step 2: Start the containersdocker compose up -d This pulls the images and starts the application, Sidekiq worker, PostgreSQL, and Redis. The first pull takes a few minutes. Subsequent starts are fast.Step 3: Prepare the databasedocker compose exec rails bundle exec rails db:chatwoot_prepare This creates the database schema and seeds the initial data, including the default administrator account.Step 4: Access the interfaceOpen your browser at http://localhost:3000. You should see the Konversio login screen.Default credentialsThe seed creates a default administrator account:Email: admin@example.comPassword: administratorChange this password immediately after logging in. See the next article for a first-login checklist.What to do nextAt this point you have a running instance with no inboxes, no agents, and a default password that needs changing. The practical next steps are:Change the default admin password and emailCreate your first inboxInvite agentsOptionally configure PilotThese are covered in detail in First login: what to set up first.Production considerationsFor anything beyond a local test, you will want to:Put a reverse proxy (nginx or Caddy) in front with TLSSet a real FRONTEND_URL in .env so email links resolve correctlyConfigure an SMTP server for outbound email (SMTP_ADDRESS and related variables)Set up regular PostgreSQL backupsThe Docker Compose setup is production-capable for small to mid-sized teams. For larger deployments, consider separating the database and Redis onto dedicated hosts.

What is Konversio?

What is Konversio?Konversio is an open-source customer support platform — a hard fork of Chatwoot CE v4.13, created in May 2026. It is MIT-licensed and developed as a non-profit project.Where it comes fromChatwoot has been open source since 2019, covering the core support platform: shared inboxes, conversations, teams, automation, and more. That openness was real and useful. But Chatwoot's AI layer — "Captain," the built-in AI support agent — was kept proprietary and enterprise-only. You could self-host Chatwoot, but you could not self-host the intelligence.Konversio forks Chatwoot CE at v4.13 and finishes what Chatwoot started: the entire stack, including the AI layer, is now open source and free for everyone.What was removedCaptain has been stripped out. It was closed-source, dependent on US-hosted AI providers, and not available to CE users. Removing it was the first step toward replacing it with something that could actually be inspected, modified, and run under your own control.What was built: PilotIn place of Captain, Konversio ships Pilot — a fully open-source AI support agent, MIT-licensed. Pilot is designed to work with open models: Gemma 4, Qwen, Whisper. It does not require an API key to a US provider. You can run the entire stack — application, database, and AI inference — on infrastructure you control.Pilot has been tested on Scaleway and Nebius as EU-hosted deployment paths, but it will run anywhere Docker runs.The missionKonversio is built for European strategic autonomy. That phrase gets used a lot in policy documents; here it means something concrete: a team in France, Germany, or anywhere else should be able to run a full-featured support platform, including AI-assisted responses, without a single request leaving their chosen jurisdiction.Chatwoot made the application layer sovereign. Konversio extends that to the AI layer. No vendor lock-in, no closed inference endpoint, no dependency on infrastructure outside your control.Tech stackThe foundation is unchanged from Chatwoot CE: Rails backend, Vue 3 frontend, Docker Compose deployment. Channels include email, live chat, WhatsApp, Telegram, and a generic API channel. All the CE features — automation, reports, help center, SLAs, webhooks — carry over intact.If you know Chatwoot, you already know most of Konversio.