---
layout: index
title: OpenTodo docs
summary: How to use OpenTodo day to day, run your own server, and connect it to other tools.
---
# OpenTodo documentation

Start with the [README](../README.md) for the feature overview, quick start and configuration table.

## Using OpenTodo

The same guides are published, with screenshots and search, at [open-todo.app/docs](https://open-todo.app/docs/). Each guide is short and opens with a screenshot; the indented pages go deeper into one topic of the guide above them.

| Guide | What it covers |
| --- | --- |
| [Getting started](getting-started.md) | From the demo or your first sign-in to adding, scheduling and completing your first task, in about five minutes. |
|   ↳ [Your first task](your-first-task.md) | The card the Inbox shows on your first visit, adding a task, giving it a date as you type, completing it, and getting the app on your phone. |
| [Open Loops](method/overview.md) | OpenTodo's own method for everything on your mind, inspired by GTD: five moves, seven principles, and how prominent the app makes it. |
|   ↳ [Catch](method/catch.md), [Clarify](method/clarify.md), [Place](method/place.md), [Do](method/do.md), [Review](method/review.md) | The five moves, one page each, with the screen and keys that serve them. |
|   ↳ [Places](method/places.md), [Rhythms](method/rhythms.md), [Horizons](method/horizons.md) | Where a task can live, the Daily check, weekly review and Monthly look, and next steps, projects and areas. |
|   ↳ [Set up in ten minutes](method/set-up.md), [Coming from GTD](method/coming-from-gtd.md) | Turn the method on and start; the GTD words you know and where they live here. |
| [Installing the app](install-app.md) | Put OpenTodo on your home screen or desktop so it opens in its own window and works offline, on iPhone, Android, Windows, macOS and Linux. |
|   ↳ [Install on your phone](install-phone.md) | Add OpenTodo to the home screen of an iPhone, iPad or Android phone, step by step, so it opens full screen and can show reminders. |
| [Tasks and projects](tasks-and-projects.md) | Add and edit tasks, write notes, break work into subtasks, set priorities and organise everything into projects and sub-projects. |
|   ↳ [The task panel](task-panel.md) | Everything in a task's panel: the title and its menu, the notes, the property chips and the Add menu, what a viewer can do, and how to close it. |
|   ↳ [Dates and times](dates-and-times.md) | How due dates and times work, every way to type or pick them, and fixing a time to a time zone for something that happens at one moment worldwide. |
|   ↳ [Deadlines and start dates](deadlines-and-start-dates.md) | A deadline is the day a task must be done by; a start date defers it until it matters. Countdowns, Someday, This Evening and the keys for each. |
|   ↳ [Notes, subtasks and dependencies](notes-and-subtasks.md) | Write formatted notes, break a task into subtasks and nest them, and make a task wait for another one with Blocked by. |
|   ↳ [Work from the list](work-from-the-list.md) | Add, complete and delete tasks, change them with one key, undo, and put them in the order you want, all without opening a task. |
|   ↳ [Change several tasks at once](bulk-actions.md) | Tick tasks with the keyboard, mouse or touch, act on all of them from one menu, preview moves and assignments, and undo the lot in one step. |
|   ↳ [Projects and sub-projects](projects.md) | Create projects and nest them, use the Project menu to colour, move, rename, archive or delete, duplicate a project or a task, and what happens when a project is done. |
|   ↳ [Project notes](project-notes.md) | The note at the top of a project: what it is for, who can edit it, Shift+P, folding long notes, and how the API and history see it. |
|   ↳ [Completed tasks in a project](completed-in-projects.md) | Keep a project's completed tasks at the end of its list in a Completed group, for lists you tick off and reuse such as groceries. |
| [Views](views.md) | Inbox, Today, Upcoming, Assigned to me, Completed and the calendar, plus views you save yourself, dashboards and the view each device opens on. |
|   ↳ [The built-in views](built-in-views.md) | What Inbox, Today, Upcoming, Anytime, Someday, Assigned to me, Calendar, Completed, Filter, Trash and Updates show, their shortcuts, and the duration filter. |
|   ↳ [Weekly review](review-and-statistics.md) | A guided weekly review with live data in seven steps, from the Inbox through every project, one card at a time, to Someday. |
|   ↳ [Statistics and the weekly digest](statistics.md) | What you completed, created and let slip computed on your device, and an optional weekly digest by email. |
|   ↳ [Process the Inbox](process-the-inbox.md) | Walk the Inbox one task at a time and decide each with a single key: today, schedule, move, delegate, label, Someday, complete or trash, with Undo. |
|   ↳ [Today and Upcoming](today-and-upcoming.md) | How Today orders overdue, started, evening and blocked tasks, how deadlines and start dates bring tasks in, and how Upcoming lays out the days ahead. |
|   ↳ [Saved views](saved-views.md) | Turn a filter query into a view pinned to the sidebar, group and sort it, manage it from its menu, and put up to six views on one dashboard. |
|   ↳ [Display mode](display-mode.md) | Show Today, Upcoming, a project or a saved view full screen in large type, for a tablet on the fridge or an e-ink panel on the wall. |
| [Search and commands](search.md) | One box on Ctrl+K finds any task, project, label, view or setting, runs any command by name, and understands filter queries. |
| [Sections and boards](sections-and-boards.md) | Split a project into stages with sections, and switch it to a board to move cards between columns by drag or keyboard. |
|   ↳ [A project on a timeline](project-timeline.md) | Show a project's tasks as bars from their start to their deadline, drag them to reschedule, and see which tasks wait for which. |
| [Attachments](attachments.md) | Add files and links to tasks and comments, offline included; limits, who can see and remove them, encryption and where the files live. |
| [Labels and filters](labels-and-filters.md) | Tag tasks across projects with labels, then find exactly what you need with the filter language and save it as a view. |
|   ↳ [Manage labels](manage-labels.md) | The labels page: rename, recolour and reorder labels, merge two into one, delete a label, and what happens when two devices create the same one. |
| [Recurring tasks and reminders](recurring-and-reminders.md) | Make a task repeat every week, month or weekday, skip an occurrence, and get reminded at the right moment. |
|   ↳ [Repeat rules](repeat-rules.md) | Every rule you can type into Repeat, the after-completion and end options, and what completing, skipping or splitting off one occurrence does. |
|   ↳ [Task reminders](task-reminders.md) | Every kind of reminder you can add to a task, how reminders follow the due date, the deadline and a repeat rule, and what happens when one goes off. |
| [Time blocking](time-blocking.md) | Estimate how long tasks take, then place them on the Day or Week calendar to see whether your plan fits the day. |
|   ↳ [Day, Week and Month](calendar-views.md) | Open the calendar, read the Day and Week grids, and use the Month overview to see six weeks at once and move tasks between days. |
|   ↳ [Place tasks on the calendar](place-tasks-on-the-calendar.md) | Drag tasks onto time slots or move them with the keyboard, change how long a block lasts, and read each day's planned hours against its capacity. |
| [Calendar feeds](calendar-feeds.md) | Show your other calendars next to your tasks in Day and Week, and subscribe to your tasks from Google Calendar, Outlook or Apple Calendar. |
|   ↳ [Other calendars in Day and Week](other-calendars.md) | Subscribe to a Google, Outlook, Apple, Fastmail or Nextcloud calendar so its events appear next to your tasks: the steps per app, refreshing, what you see, and the limits. |
| [Sharing and comments](sharing.md) | Share a project with people on your server, choose what they can do, assign tasks, and talk it through in comments with @mentions. |
|   ↳ [Invite people](invite-people.md) | Invite links that bring one person into a project, who may create accounts with them, and server invitations for people who have no account yet. |
|   ↳ [Roles and assignments](roles-and-assignments.md) | What viewers, editors, admins and the owner can do in a shared project, leaving or handing over a project, and assigning tasks to members. |
|   ↳ [Comments and activity](comments-and-activity.md) | Talk a task through in its comment thread with @mentions, replies and formatting, and follow what others changed in the Updates feed and a project's activity. |
|   ↳ [Public links](public-links.md) | Share a project's list with anyone who has the link, no account needed: view-only or with ticking, named, with an optional expiry, and revoked in one click. |
| [Use AI with OpenTodo](ai-and-agents.md) | Three ways to bring an AI assistant to your tasks: the assistant in the app, an assistant you already use over MCP, or a coding agent with the ot command. Which to pick and what each can touch. |
|   ↳ [What AI assistants can and can't do](ai-limits.md) | The rules shared by the in-app assistant, MCP and the ot command: who switches them on, what they can reach, how changes are recorded and limited, and prompt injection. |
| [AI assistant](assistant.md) | Plan and change your tasks by talking, with a model provider your server owner chooses. Every change is proposed for review and can be undone. |
|   ↳ [Ask, review and undo](assistant-ask.md) | Open the assistant, ask a question, review the changes it proposes, apply the ones you want and undo them in one step. |
|   ↳ [Skills, pasted notes and safety](assistant-skills.md) | The assistant's ready-made jobs, how pasted text is kept apart from instructions, and what the assistant can never do on its own. |
|   ↳ [Assistant settings](assistant-settings.md) | Your part of Settings → Integrations → Assistant, using your own Anthropic, OpenAI or Gemini key instead of the server's, and letting small changes skip the review. |
|   ↳ [What the assistant sends and keeps](assistant-privacy.md) | What is sent to the model provider and when you agree to it, where conversations live, how tokens are counted, and why encrypted accounts have no assistant. |
|   ↳ [Set up the assistant](assistant-setup.md) | For the server owner, allow one or more model providers, enter models and keys, test the connection and turn the assistant on for everyone. |
|   ↳ [Assistant owner options](assistant-owner-options.md) | Running the assistant on a local model, letting members bring their own key, counting their keys toward the limit, and the monthly token allowance. |
| [Notifications](notifications.md) | The bell for assignments, mentions and tasks ready to start, reminder pop-ups inside the app, and push notifications on each device when the app is closed. |
|   ↳ [Push notifications](push-notifications.md) | Turn on reminders for when the app is closed, device by device, what iPhone and iPad need, what a push message contains, and what to do when nothing arrives. |
|   ↳ [Check that push works](push-delivery-check.md) | The Delivery check under Settings → Notifications, each step it lists, and what every result of a test notification means. |
| [Offline and sync](offline-and-sync.md) | How OpenTodo keeps working without a connection, what the sync status means, and what happens when two devices change the same task. |
| [Keyboard shortcuts](keyboard.md) | Every shortcut in OpenTodo, from quick add to the calendar, plus the optional Vim keybindings. |
| [Account security](account-security.md) | Sign in with a passkey, add two-factor authentication, change your password and check where your account is signed in. |
|   ↳ [Two-factor authentication](two-factor.md) | Add a six-digit code from an authenticator app to your sign-in, remember a browser for 30 days, and keep recovery codes for when you lose your phone. |
| [Import and export](import-export.md) | Download everything you have as one file, and bring tasks in from a spreadsheet, another OpenTodo server or other task apps. |
|   ↳ [Import step by step](import-steps.md) | Choosing a file, checking the preview, the options for projects, time zones and sections, duplicates, undoing an import, and the limits. |
|   ↳ [Project templates](templates.md) | Save a project as a template file, start a fresh project from one with the dates counted from your start day, and how that differs from Import. |
| [Trash and history](trash-and-history.md) | Restore deleted tasks and projects from the Trash, see every change made to a task, and bring back an earlier value. |
|   ↳ [Task history](task-history.md) | Every change to a task is kept: see who changed what and from where, restore one value or a whole version, and follow the activity of a task. |
|   ↳ [Archived projects](archived-projects.md) | Archiving hides a finished project without deleting it. When OpenTodo offers to archive, automatic archiving after 30 days, and how to bring a project back. |
| [Settings](settings.md) | A tour of Settings, what each section does, which choices belong to one device and which follow your account. |
|   ↳ [Settings: You](settings-you.md) | The Account and Appearance sections of Settings, your profile, session, password, two-factor authentication, passkeys, encryption, and the mode, theme, density and sidebar. |
|   ↳ [Settings: App](settings-app.md) | The General, Notifications and Capture sections of Settings, the start view, date and time formats, the calendar grid, keyboard options, quick add, voice and email to task. |
|   ↳ [Settings: Data](settings-data.md) | The Integrations and Data sections of Settings, CalDAV, calendar feeds, webhooks, API tokens, the assistant and MCP, export, import, attachments and archived projects. |
|   ↳ [Settings: Server](settings-server.md) | The People and Server sections of Settings, for the owner and admins. Users, invitations, the two-factor policy, single sign-on, backups, attachment limits and the audit log. |
| [Troubleshooting and FAQ](troubleshooting.md) | Fixes for the usual hiccups, from a task that seems to be missing to reminders that don't arrive, and answers to common questions. |
|   ↳ [Sync, sign-in and sharing problems](troubleshooting-sync.md) | What to check when a task seems to be missing, a change doesn't reach your other device, you can't sign in, or a shared project won't let you in. |
|   ↳ [Notifications, install and app problems](troubleshooting-app.md) | What to check when reminders don't arrive, the app won't install, a passkey can't be added, quick add misreads a word, or the app looks old or breaks on screen. |

### Reference

| Page | What it covers |
| --- | --- |
| [Quick add syntax](quick-add.md) | Natural-language capture in six languages, preview chips, voice capture |
| [Filter queries](filters.md) | The filter language, the Filter view, saved views and dashboards |
| [Recurring task rules](recurrence.md) | Rule grammar, how next dates are computed, completing, skipping and detaching |
| [Reminders reference](reminders.md) | Relative and absolute reminders, snooze, web push and its privacy |
| [Capturing pages](capture.md) | Share sheet, bookmarklet and browser extension |
| [Import formats](import.md) | Own export, CSV and other apps' JSON exports; duplicates and undo |
| [End-to-end encryption](e2ee.md) | What is encrypted, the threat model, devices, recovery and limits |
| [Feedback and support](feedback-and-support.md) | Where to report a problem or suggest an idea, how to star OpenTodo on GitHub, and how to buy the maintainer a coffee. |

## Self-hosting and operations

| Guide | What it covers |
| --- | --- |
| [Running with Docker](self-hosting/docker.md) | Compose, `docker run`, reverse proxies, push, bind mounts, recovery commands |
| [Deploying on Coolify](self-hosting/coolify.md) | One-click deployment from the compose file, environment variables, troubleshooting |
| [Running on Unraid](self-hosting/unraid.md) | Install from Community Applications, settings, appdata permissions, https, updates and backups |
| [Running on CasaOS and ZimaOS](self-hosting/casaos.md) | App store or custom app, settings, the data folder, https, updates and backups |
| [Running on Cosmos Cloud](self-hosting/cosmos.md) | Market or custom compose, the setup token, the address, updates and backups |
| [Running on Dokploy](self-hosting/dokploy.md) | Templates or a templates base URL, the setup token, http and https domains, updates and backups |
| [Running on Easypanel](self-hosting/easypanel.md) | App service or template, the setup token, the https domain, updates and backups |
| [Running on Portainer](self-hosting/portainer.md) | App Templates, settings, the volume, https and reverse proxies, updates and backups |
| [Running on Runtipi](self-hosting/runtipi.md) | Adding OpenTodo's app store, settings, the data folder, https, updates and backups |
| [Running on TrueNAS](self-hosting/truenas.md) | Install via YAML or the Apps catalogue, settings, dataset permissions, https, updates and backups |
| [Running on Umbrel](self-hosting/umbrel.md) | The App Store package, the first account, Umbrel login and the routes it lets through, settings, updates |
| [Running on CapRover](self-hosting/caprover.md) | One-click app or pasted template, the setup token, https then the base URL, the volume, updates and backups |
| [Running on Fly.io](self-hosting/fly.md) | `fly launch` from the repository's `fly.toml`, the setup token as a secret, one always-on machine with a volume, updates and backups |
| [Running on Kubernetes](self-hosting/kubernetes.md) | The Helm chart, the setup token, Ingress and https, one pod by design, security, updates and backups |
| [Running with Podman](self-hosting/podman.md) | A Quadlet systemd service, rootful or rootless, `podman auto-update`, the data volume and backups |
| [Running on Render](self-hosting/render.md) | Deploy to Render Blueprint, the paid instance and disk it needs, the setup token, custom domains, updates and backups |
| [Running on Synology](self-hosting/synology.md) | Container Manager project, the data folder and its owner, https with DSM's reverse proxy and Let's Encrypt, updates and backups |
| [Public demo instance](self-hosting/demo.md) | `OPENTODO_DEMO=true`: a private sandbox per visitor, limits, expiry and the nightly reset, what is switched off, Docker and Coolify |
| [Outgoing email](self-hosting/outgoing-email.md) | Optional SMTP for password resets, verified sign-up and invitations; Settings or `OPENTODO_SMTP_*`, providers, troubleshooting |
| [Single sign-on](self-hosting/sso.md) | Connecting an OpenID Connect provider, linking, SSO-only mode, break-glass |
| [Host mode](self-hosting/host-mode.md) | For a hosted service: many tenants in one process by host name, limits, the operator interface |
| [Backups](backups.md) | Scheduled backups to disk, S3 or WebDAV, encryption, restore, archive format |
| [Email to task](email.md) | Pointing OpenTodo at an IMAP mailbox, provider notes, protection |
| [Calendar apps (CalDAV)](caldav.md) | Enabling CalDAV, app passwords, client setup, what maps to what |

The full list of environment variables is in the [README](../README.md#configuration); security details are in [SECURITY.md](../SECURITY.md).

## Integrations

| Guide | What it covers |
| --- | --- |
| [HTTP API](api.md) | Authentication, every route, entity fields, error codes, examples |
| [Command-line client](cli.md) | `ot`: install, sign in, commands, JSON output and exit codes |
| [Webhooks](webhooks.md) | Events, payload, signature verification, retries, receiver recipes |
| [AI assistants (MCP)](mcp.md) | Enabling the MCP endpoint, read-only and assistant tokens, read and write tools, limits, prompt-injection safety |

## Internals

| Guide | What it covers |
| --- | --- |
| [Architecture](architecture.md) | Data flow, server packages, tables, client modules, build |
| [Sync protocol](sync.md) | Operations, schema, winner rule, exchange, sharing scopes, live updates, purge |
| [Translating OpenTodo](translating.md) | How app text is written for translation, catalogs, checks, adding a language, glossary |

## Project

[Changelog](../CHANGELOG.md) · [Roadmap](../ROADMAP.md) · [Security policy](../SECURITY.md) · [Contributing](../CONTRIBUTING.md)