User Guide

Open your WarmDesk URL in a browser. If public registration is enabled you will see a Register link on the login page. Fill in a username, display name, email address, and password and click Register. You are logged in immediately.

If registration is not available, ask an administrator to create an account for you.

Enter your username and password, or sign in with a registered passkey. WarmDesk issues a short-lived JWT access token (15 minutes) and a 7-day refresh token that keeps you logged in as long as your browser tab is open.

By default the session expires after 60 minutes of inactivity; your administrator can change or disable this timeout.

Click Forgot password? on the login page and enter your email address. If an account with that address exists, a reset link is sent immediately. The link is valid for one hour.

You can enable TOTP-based MFA from Settings → Security. Scan the QR code with an authenticator app (Aegis, Authy, Google Authenticator, etc.) and enter the 6-digit code to confirm. Once enabled, every login requires the one-time code after the password. If your administrator allows it, you can mark a device as trusted to skip MFA on it for 7 or 30 days.

WarmDesk is also available as a native desktop app (Linux AppImage, macOS DMG, Windows installer) that asks for your server URL on first run.

Click + New Project on the dashboard. Choose a name, a card prefix (e.g. PRJ, used in card numbers and fixed after creation), a colour, and a board type (Kanban or Scrum).

If you don’t see the + New Project button, your administrator has not granted you permission to create projects.

Kanban — columns you define, cards flow freely between columns. Suitable for continuous-flow work.

Scrum — same column structure but with sprints, a backlog, epics, and story points.

Open Project Settings → Members to invite people as Viewer (read-only), Member (create and edit cards, comment, chat), Admin (also manage columns), or Owner (also manage members and webhooks, delete the project).

Star a project with the ⭐ icon to pin it to Favorite Projects in the sidebar. Drag favourites to reorder them. Filter the dashboard by customer using the dropdown at the top.

Owners can close a project from Project Settings → General → Danger Zone. A closed project is hidden from the sidebar and project list but stays reachable by its URL and can be reopened at any time.

Add columns with + Add Column in the board toolbar (project admins and owners). Click a column title to rename it; drag the column header to reorder; remove an empty column with the trash icon.

Open Column settings (⚙) on a column header to change its colour and optional WIP limit (maximum cards). The header shows count versus limit (for example 3 / 5); it is emphasized when the column is at or over the limit. Leave the limit empty to turn off WIP tracking.

Click + Add card at the bottom of a column to create a new card. Drag cards between columns and within a column to reorder them, or use a column’s sort controls (date, assignee, priority). Click a card to open the card detail panel.

The Table View button in the board toolbar swaps the lanes for a flat, sortable table of every card in the project: reference, title, column, priority, assignee, due date, story points, time spent, and closed state. Click a column header to sort (click again to reverse), and a title to open the card. Hide Closed works in both views, and your choice of view is remembered in this browser.

Click Gantt in the board toolbar for a timeline of every card with a start or due date. Switch between Day, Week, and Month zoom; click a bar to open the card.

Scrum projects add a Backlog view (prioritise cards by dragging, assign them to sprints), an Epics view for grouping cards across sprints, and a Sprint Board showing only the active sprint. Create a sprint, add backlog cards to it, and click Start to begin. When you complete a sprint, unfinished cards return to the backlog.

Click 📊 Charts in the board toolbar to open the analytics view. Kanban projects include four charts:

Use the time-range selectors at the top of each chart to adjust the window.

Scrum projects add these charts:

Use the ⋮ menu in the card’s top-right corner to show or hide optional sections (attachments, checklist, labels, tags, watchers, sub-cards, linked cards, …); a section with content is always shown.

Add checklist items in the Checklist section and drag the ⠿ handle to reorder them. Each item has its own checkbox; the card shows a completion ratio (e.g. 3/5).

Add a comment at the bottom of the card detail; click Reply under a comment to quote it. Comments can carry attachments too — paste a screenshot or attach a file directly in the comment box. To log time with the comment, fill in the hours and minutes fields. Logged time appears in the board time report.

Drag files or click the upload zone to attach them. Images are displayed inline; other file types appear as download links. MIME type is detected server-side; the client-supplied content type is ignored.

Add yourself or colleagues as watchers to receive notifications when the card is updated.

Every card gets a sequential number like PRJ-42. Type this number in any chat message or comment to generate a clickable badge that opens the card, or use it in commit messages to link git events to the card. A card moved to another project gets a new number there, but its old number keeps working everywhere.

Every project has a persistent chat channel, opened from the Project Chat entry in the sidebar of the project’s Topics page. All project members can read and post, including pasted screenshots and file attachments. Use the ⋮ menu at the top of the Topics sidebar to hide the entry if you don’t use it.

Open Chats in the header (or click a name under People in the sidebar) to access direct messages and group chats.

Start a 1-on-1 conversation from any user, or click New Conversation and create a group chat by selecting multiple users. The Teams tab pre-fills all members of one of your projects in a single click. Group chats support a custom avatar and member management (add / remove participants).

Chat messages support:

WarmDesk supports two call modes in direct messages:

Use the camera button in the chat header to start a video call, or the mic button next to it for a voice-only call that never asks for camera access. During a call you can share your screen, see when the other party is muted, and use a resizable in-call text chat. If the server has not configured LiveKit yet, group chats show a status banner explaining that group calls are unavailable.

Click the pop-out button in the call controls to shrink the call into a small floating window that you can move and resize (also with the keyboard), so you can keep working while on the call; click it again to return to full screen.

Each row is a customer + project + activity combination; columns are the days of the week, with today highlighted. Click a cell to enter the hours worked that day; row, day, and week totals update automatically.

Select a cell, then Shift+click or Shift+arrow keys to extend a rectangular selection. Ctrl+C / Ctrl+X / Ctrl+V (⌘ on macOS) copy, cut, and paste minutes, start/end times, holiday flag, and distance. A single copied value fills every selected cell; a copied block pastes as a grid. The clipboard survives switching weeks, so you can copy Monday of one week into Monday of another.

Click the 📅 button next to Edit macros to switch the Log Time tab between the weekly grid and a drag-and-drop calendar (choose which one opens by default in Settings). Entries with a start and end time appear as coloured blocks; entries without times are listed in an Unscheduled strip. Blocks are coloured by customer by default, or by project via the Calendar block color setting.

Macros, Copy Previous Week, Undo, and the export buttons work in the calendar view too.

If a customer has locations with a standard travel distance, a Location picker appears wherever a distance can be set: the add/edit row forms, the per-cell distance popup, the calendar entry form, and macro rows. Picking a location fills in its distance (still editable afterwards) and remembers the chosen location on the entry. Re-picking a row’s location also updates that week’s entries on the row that already have a distance; days left blank stay untouched.

Store recurring weekly patterns (for example travel out, preparation, teaching, travel home) as time macros. Open the editor with ⚡ in the top bar to create, duplicate, import, or export macros; each row presets customer, project, activity, hours, optional start/end times, distance, and location — either the same for every day or as an alternating A/B pattern. Run a macro from ⚡ Macro in the bottom bar: pick the macro and the start day, and it fills the current week. Macros are stored on the server, so they follow you across devices.

The ⚙ button on the time-tracking tab bar manages lightweight projects and customers that exist only for time tracking (no board, no CRM entry). A project can have undeclarable minutes (e.g. travel time) that are subtracted from declarable totals in the sheet, report, and exports. Projects and customers created by an administrator are marked Global (created by admin) and are visible to everyone.

With time tracking enabled, the stopwatch button in the top bar starts a timer: pick a project (and a customer if the project has none), add a description, and click Start. While it runs, the button shows the elapsed time; click it to Stop and book, Switch… to another task (the running timer is booked first), or Discard it. Time is rounded up to whole 15 minutes and split at midnight. The desktop app’s tray menu has the timer as well. It’s the same timer as warmdesk-timer below: start it in the browser, stop it in a terminal, and every open WarmDesk window follows along.

warmdesk-timer starts a timer when you begin and books the time when you stop. The Linux desktop packages (.deb, .rpm) install it as /usr/bin/warmdesk-timer; it also comes with the server download and as a single file for Linux, macOS, and Windows on the release page. Give it your server and a personal API key (Settings → API Keys) in timer.yaml (see below), or through WARMDESK_URL / WARMDESK_API_KEY.

Starting while a timer runs books the running one first. Time is rounded up to whole 15 minutes and split at midnight; the entries show up in the weekly grid, calendar, and reports like any other. Run warmdesk-timer projects to see what you can book on, and warmdesk-timer help for all options.

The Report tab shows your own entries for a week, month, year, or custom range, grouped by period, customer, project, or customer + project. Each group header shows the number of entries and the group total, in the exports too. Switch between a table and a chart (bar, pie, or stacked bar). The chart shows the ten activities with the most time and adds the rest together as Other; click Other (or the button below the chart) to see the next ten, and Back to return. A table below the chart lists every activity with its time and share of the total. Export options control font, PDF language, a page per customer, costs, distances, and undeclarable time before you download a PDF or XLSX. When grouped by customer, billable groups offer a Create Invoice button.

The Board tab (formerly Reports, which still redirects there) reports time logged on cards per project, filterable by period, project, and assignees, and exports to PDF or XLSX. All exports are generated on the server.

A ticket of type Problem records a root cause, a workaround, and whether it’s a known error. Link incidents to it with caused by and resolve them all at once when the problem is fixed. The Problems page lists all problems and, with Known errors only, works as the known error database.

Articles are internal (agents only) or public (also shown in the customer portal). Each ticket suggests matching articles; agents can link an article or create an article from this ticket.

Order a service from the Service catalogue by filling in its form; this creates a service request routed to the right group. Requests and changes can need approval from a group: approvers decide on the Approvals page, and until then the ticket can’t be started or resolved.

A Change request follows the change workflow: draft, awaiting approval (by the change advisory board; standard changes are pre-approved), approved, scheduled, implementing, review, and completed or failed. Fill in the risk, planned window, and implementation, backout, and test plans. Freeze windows block scheduling except for emergency changes. The Change calendar shows all changes by month, by week, or as a list.

The CMDB holds your configuration items with their relations. Impact analysis shows what is affected when an item fails or changes.

The Ticket report shows created and resolved tickets, backlog, MTTR, first response, SLA compliance, first-contact resolution, and reopen rate, with breakdowns and PDF/Excel export.

Users with the customer role only see the helpdesk, their own customers' tickets, the public knowledge base, and the service catalogue.

Click the ⇄ icon next to the search box to find and replace text across Cards, Card comments, Direct messages, Tickets, and Time entries. Choose the categories and how many results per type to show, then click Preview to see a before/after snippet for every match. Matches you are not allowed to edit are greyed out; uncheck anything you want to keep and click Replace to update only the checked rows. Project chat messages can be searched but not replaced.