Appearance
Crosdesk documentation
Crosdesk is a work-tracking tool for organisations that run several departments against a shared set of projects. It covers the whole path from an idea to the version that shipped it.
These pages are the product manual. They are written for the people using Crosdesk, not for the people building it — where a rule exists, the reason it exists is given, because almost every rule here was put in to stop something specific going wrong.
Getting started
| Page | What it covers |
|---|---|
| What Crosdesk is | The ideas everything else rests on |
| Signing in | Accounts, workspaces, passwords |
| Finding your way around | The navigation, section by section |
| Connecting an agent | Personal access tokens, and letting Claude Code or another MCP client work as you |
| Video tutorials | Twenty narrated walkthroughs, and the pages each one goes with |
The lifecycle
The order below is the order work moves in. Each page assumes the one before it.
| Page | What it covers |
|---|---|
| Overview | The whole path on one page |
| Departments and people | Who sees what, and why |
| Projects and the canvas | Shaping work, and Verify |
| Tasks | The unit of work, and everything on it |
| Epics | Headings over work that already exists |
| The backlog | What is waiting, and what is committed |
| Sprints and the board | The cadence, and ending one |
| Unplanned work | What arrives mid-sprint |
| Features | Phases, steps, approvals, issues |
| Releases | What went out, and when |
| Reports | Thirteen questions, and what each will not answer |
| Recordings | A bug's video, console and network log, linked to the work |
| Linking pull requests | The references a pull request writes to link itself |
| Todos | Short assigned actions on work, and your personal list |
| Calendar and meetings | Your private diary, repeating meetings and linked actions | | Documents | Markdown documents in department folders, with saved and released versions |
Guides
Step-by-step walkthroughs with pictures, for when you are doing it the first time. Each step links to the reference page above that explains its rules.
| Page | What it covers |
|---|---|
| Running a project | Create, draw the canvas, verify, plan into sprints, follow and ship |
| Running a feature | Steps and people, schedule and baseline, review, issues, the next round |
Self-hosting
For whoever runs the installation — the instance operator. Nobody else needs these pages.
| Page | What it covers |
|---|---|
| Installing | Docker Compose, the .env file, HTTPS in front, and what to do when it will not start |
| First boot and the operator console | Claiming /super-admin, mail, storage, and creating workspaces |
| The licence | What a licence holds, installing and renewing it, and what happens when it lapses |
| Upgrading and backups | New versions, rolling back, backups, rotating the encryption key, nightly jobs |
Administration
| Page | What it covers |
|---|---|
| Departments | Creating them, and what archiving does |
| Users | Inviting, department membership, deactivating |
| Groups and permissions | The two capabilities, and how they combine with departments |
| Labels | The shared vocabulary |
| Working days | Weekends and holidays, and what plans do with them |
| Audit log | Who did what, from where |
| Sign-in providers | Google, GitHub and OIDC sign-in, for the instance operator |
| Recordings settings | Letting the Recorder in, retention and length, for the instance operator |
| Video calls | Zoom setup; Google Meet OAuth with Google Cloud screenshots; Workspace delegation and instance settings |
| GitHub | The workspace's GitHub App: creating it, installing it, shared repositories |
| Agents | Every agent connected to the workspace, revoking them, and turning agents off |
Screenshots come from the demo workspace, which any installation can recreate with pnpm db:reset && pnpm db:seed && pnpm db:populate. The Todo screenshot comes from the disposable fixtures in pnpm test:todos <api-url> --browser. Calendar screenshots come from pnpm test:meetings <api-url> --browser disposable fixtures. Video-call console and meeting screenshots come from pnpm test:video-rooms <api-url> --browser --screenshots. The Zoom Marketplace setup screenshots use an existing Server-to-Server OAuth app: app type, App Credentials, Scopes and Activation. Credential values are replaced with examples before capture, and the personal profile header is excluded. Capture these screens without saving app changes; the app-type screenshot stops before Create. The guides' screenshots, and the feature board's, come from node scripts/docs-screenshots-guides.mjs against pnpm dev on the demo workspace; it opens screens and dialogs and never saves, so the demo is unchanged afterwards. Google Meet OAuth screenshots were captured from Google Cloud and the deployed Crosdesk console and profile. They cover the enabled Meet API, Branding, Audience and test users, Data access, a Web application client, Google consent, the connected-account cards and a saved Meet meeting. Example addresses, client IDs, hostnames and meeting text replace real values in the displayed page before capture; no form events or saves apply those examples. Google consent screenshots show a previously authorised account, and its services dialog lists the existing permissions. The screenshot-only reconnect is cancelled before the final grant. Workspace delegation images come from Crosdesk only: an empty, unsaved key editor and the delegated-user test form, with no claim of a successful delegation. Crop out browser tabs and personal account headers; keep secrets masked. Capture these pages without saving settings or meeting changes.
Every image here is reproducible rather than a one-off.