Poznote

Features

Discover all the features here.

Screenshots

See all the screenshots here.

Demo

https://demo.poznote.com

Login: poznote Password: poznote

Don't want to manage a server?

A hosting company can run Poznote for you. Compare the hosts or deploy directly:

They talk about Poznote

https://poznote.com/press.html

Discord

Join the community to ask questions, share feedback or follow the development:

https://discord.gg/fuEV6uqf4N

Table of content

• Install
• Access
• Change Settings
• Update application
• Authentication
• App Passwords
• Note types
• Revisions
• Personalization
• Multi-users
• Sharing and collaboration
• Speed dial
• Activity Log
• Webhooks
• Git Synchronization
• S3 Attachment Storage
• Backup / Export
• Restore / Import
• Offline
• Multiple Instances
• AI Assistant
• Transcription (speech to text)
• MCP Server
• Applications
• Chrome Extension
• Share to Poznote on Android
• API Documentation
• Tech Stack

Install

The official image is multi-arch (linux/amd64, linux/arm64) and supports Windows/macOS via Docker Desktop, as well as ARM64 devices like Raspberry Pi, NAS systems etc.

Choose your preferred installation method below:

Step 1: Prerequisite

Install and start Docker Desktop

Step 2: Deploy Poznote

Create a new directory:

mkdir poznote

Navigate to the Poznote directory:

cd poznote

Create the environment file:

curl -o .env https://raw.githubusercontent.com/timothepoznanski/poznote/main/.env.template

Edit the .env file:

notepad .env

Download the Docker Compose configuration file:

curl -o docker-compose.yml https://raw.githubusercontent.com/timothepoznanski/poznote/main/docker-compose.yml

Download the latest Poznote Webserver and Poznote MCP images :

docker compose pull

Start Poznote containers:

docker compose up -d

Step 1: Prerequisite

1. Install Docker engine
2. Install Docker Compose

Step 2: Install Poznote

Create a new directory:

mkdir poznote

Navigate to the Poznote directory:

cd poznote

Create the environment file:

curl -o .env https://raw.githubusercontent.com/timothepoznanski/poznote/main/.env.template

Edit the .env file:

vi .env

Download the Docker Compose configuration file:

curl -o docker-compose.yml https://raw.githubusercontent.com/timothepoznanski/poznote/main/docker-compose.yml

Download the latest Poznote Webserver and Poznote MCP images:

docker compose pull

Start Poznote containers:

docker compose up -d

Step 1: Prerequisite

Install and start Docker Desktop

Step 2: Deploy Poznote

Create a new directory:

mkdir poznote

Navigate to the Poznote directory:

cd poznote

Download the environment file:

curl -o .env https://raw.githubusercontent.com/timothepoznanski/poznote/main/.env.template

Edit the .env file:

vi .env

Download the Docker Compose configuration file:

curl -o docker-compose.yml https://raw.githubusercontent.com/timothepoznanski/poznote/main/docker-compose.yml

Download the latest Poznote Webserver and Poznote MCP images:

docker compose pull

Start Poznote containers:

docker compose up -d

Don't want to manage a server? A hosting company can run Poznote for you and keep it online. See the available hosts and how to choose between them here.

On a Proxmox VE host, the Proxmox VE Community Scripts project installs Poznote in its own container with a single command, no Docker involved: it creates an unprivileged Debian 13 LXC (1 vCPU, 512 MB of RAM and a 4 GB disk by default) and serves Poznote from nginx and PHP inside it.

Run this from the Proxmox host shell:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/poznote.sh)"

Poznote then answers at http://<container-ip>:8040, with the same default credentials as any other install. To update it later, run update in the container console.

This script is written and maintained by the community, not by Poznote. See the Poznote script page for its options and notes.

Step 1: Prerequisite

Install Helm and make sure your Kubernetes context points to the cluster where you want to deploy Poznote.

Step 2: Deploy Poznote

Add the HelmForge chart repository:

helm repo add helmforge https://repo.helmforge.dev

Update your local chart index:

helm repo update

Install Poznote:

helm install poznote helmforge/poznote --namespace poznote --create-namespace

The Poznote Helm chart is maintained by the HelmForge community as a Kubernetes-native installation option. See the HelmForge Poznote chart documentation for values, persistence, service exposure, probes, security contexts, and other production-oriented settings.

Poznote also ships a rootless image variant that runs entirely as an unprivileged user (uid/gid 1000) instead of root — for environments that forbid root inside containers (Kubernetes restricted PodSecurityStandard, rootless Podman, docker run --user, etc). It works exactly like the default image; the only differences are that it listens internally on port 8080 and cannot fix the ownership of your data directory at startup.

Step 1: Prerequisite

1. Install Docker engine
2. Install Docker Compose

Step 2: Deploy Poznote

Create a new directory:

mkdir poznote

Navigate to the Poznote directory:

cd poznote

Create the data directory and make it owned by uid/gid 1000 (required: unlike the default image, the rootless container cannot fix this ownership itself at startup):

mkdir -p data
sudo chown -R 1000:1000 data

sudo is often not needed here: if your user already has uid 1000 the chown can be skipped, and on rootless Podman/Docker it can run without root, see Running rootless.

Create the environment file:

curl -o .env https://raw.githubusercontent.com/timothepoznanski/poznote/main/.env.template

Edit the .env file:

vi .env

Download the rootless Docker Compose configuration file:

curl -o docker-compose.rootless.yml https://raw.githubusercontent.com/timothepoznanski/poznote/main/docker-compose.rootless.yml

Download the latest Poznote rootless Webserver and Poznote MCP images:

docker compose -f docker-compose.rootless.yml pull

Start Poznote containers:

docker compose -f docker-compose.rootless.yml up -d

To migrate an existing Poznote instance to the rootless variant, or for more details, see Running rootless in the Troubleshooting Guide.

If you encounter installation issues, see the Troubleshooting Guide.

Access

After installation, access Poznote in your web browser:

http://localhost:8040

• Username: admin_change_me
• Password: admin
• Port: 8040

Rename the default administrator account and change the default password after the first login.

Change Settings

Most day-to-day settings are changed from the Poznote interface. Use the .env file only for deployment/runtime values that are read when containers start.

• HTTP_WEB_PORT
• POZNOTE_OIDC_CLIENT_ID
• POZNOTE_OIDC_CLIENT_SECRET
• POZNOTE_OIDC_DISABLE_NORMAL_LOGIN
• Optional runtime overrides such as POZNOTE_MCP_PORT and POZNOTE_DEBUG
• POZNOTE_PHP_FPM_MAX_CHILDREN to change the number of simultaneous PHP requests (default 10) on a busy instance, see the Troubleshooting Guide
• POZNOTE_PHP_MEMORY_LIMIT to change the PHP memory limit per request, in MB (default 512), see the Troubleshooting Guide
• POZNOTE_LISTEN_PORT to change the port the web server listens on inside the container (default 80), only needed with network_mode: host, see the Troubleshooting Guide
• POZNOTE_SETTINGS_PASSWORD to ask for an extra password before the Settings page opens, left empty by default
• POZNOTE_MCP_AUTH_TOKEN to require a bearer token from MCP clients, and the other POZNOTE_MCP_* variables, which choose how clients sign in and which tools they reach, see MCP Server

• Admin/global settings such as OIDC provider settings, Git Sync enablement, import limits, and custom CSS upload
• User/profile settings such as local account passwords, theme, font sizes, note sorting, workspace background, and hidden UI elements

Modify System Settings (.env)

Navigate to your Poznote directory:

cd poznote

Stop the running Poznote containers:

docker compose down

Edit your .env file with your preferred text editor (e.g., nano .env or notepad .env).

Save the file and start the containers again to apply changes:

docker compose up -d

Update application

Navigate to your Poznote directory:

cd poznote

Stop the running containers before updating:

docker compose down

Download the latest Docker Compose configuration:

curl -o docker-compose.yml https://raw.githubusercontent.com/timothepoznanski/poznote/main/docker-compose.yml

Download the latest .env.template:

curl -o .env.template https://raw.githubusercontent.com/timothepoznanski/poznote/main/.env.template

Use sdiff to review .env.template and add any new variables to your .env file if needed:

sdiff .env .env.template

Download the latest Poznote Webserver and Poznote MCP images:

docker compose pull

Start the updated containers:

docker compose up -d

Your data is preserved in the ./data directory and will not be affected by the update.

Beta versions

Beta versions bring new features before they are released as stable, and are listed as pre-releases on the releases page. They are published under the latest-and-beta tag, which always points to the newest version, beta or stable.

To use them, change the two image lines of your docker-compose.yml and keep the rest of the file as it is:

services:
  webserver:
    image: ghcr.io/timothepoznanski/poznote:latest-and-beta
    ...
  mcp-server:
    image: ghcr.io/timothepoznanski/poznote-mcp:latest-and-beta
    ...

With the rootless variant, the webserver image in docker-compose.rootless.yml becomes poznote:latest-and-beta-rootless, and the MCP image is the same poznote-mcp:latest-and-beta.

Download the images and restart the containers:

docker compose pull
docker compose up -d

• Before switching: a beta can still contain bugs, so make a backup first. Problems can be reported in the GitHub issues or on Discord.
• Updates: each docker compose pull then gets the newest beta, or the stable version once it is released. The update procedure above downloads a new docker-compose.yml that uses the stable tags again, so change the two image lines once more after that step.
• Back to stable: a beta can change the database, so going back to an older stable version may not work. Wait for the next stable version, which includes the changes of the beta, then follow the update procedure above.

Authentication

Poznote supports multiple authentication methods including local accounts and external identity providers. Apps and extensions that talk to the REST API use app passwords, a separate credential described in the next section.

Poznote authenticates users against their profile using a username or email address and a password.

Default account

On a fresh installation, Poznote creates one active administrator profile:

• Username: admin_change_me
• Password: admin

Change the default password and rename the account after the first login.

Password management

Passwords are managed through the Poznote web interface, not through .env:

• Users can change their own password from Settings > Change Password.
• Administrators can set a custom password for any user or reset it to the default from Settings > Admin Tools > User Management.
• The Remember me option keeps the session for 30 days.
• Changing a password invalidates existing remember-me cookies for that user.

Two-factor authentication

Each user can turn on two-factor authentication (TOTP) from Settings > Two-factor authentication. After the password, the login form then asks for a 6-digit code from an authenticator app (Aegis, Google Authenticator, 1Password, Bitwarden...).

• Setup shows a QR code, drawn in the browser, and ten single-use recovery codes to keep in case the phone is lost.
• It protects password sign-in. An SSO login is left to the identity provider and its own second factor.
• While it is on, the REST API no longer accepts the account password on its own: give clients an app password, or send the current code in the X-Poznote-OTP header.
• An administrator can turn it off for a user who lost both their device and their recovery codes, from Settings > Admin Tools > User Management (password dialog).
• An administrator can make it mandatory for every account that signs in with a password, from Settings > Admin Tools > Require two-factor. An account without it sets it up at its next sign-in (QR code and first code on the login page), sessions opened without it end, and its owner can no longer turn it off. SSO sign-ins are not concerned.
• Turning it on or off invalidates existing remember-me cookies for that user.

Default passwords

• Administrator accounts: admin
• Standard user accounts: user

When a user has not yet changed their password, the default value above is used. Once a password is changed through the interface, a secure bcrypt hash is stored in the database and takes priority.

Poznote supports OpenID Connect (authorization code + PKCE) for single sign-on integration. This allows users to log in using external identity providers such as Auth0, Keycloak, Azure AD, or Google Identity.

How it works

1. The login page displays a Continue with [Provider Name] button when OIDC is enabled.
2. Users authenticate with the OIDC authorization code flow secured by PKCE.
3. Access can be restricted with allowed groups and, if needed, a legacy allowed users list.
4. After authentication, Poznote links the identity by sub (oidc_subject), then by a verified email (one set by an admin or synced from the provider, case does not matter). An existing profile is never linked by its username: to link one on its first SSO login, give it the email the provider sends, or paste its OIDC subject, in Settings > Admin Tools > User Management. A refused first login logs the subject to paste.
5. If auto-create users is enabled and no profile matches, Poznote creates one automatically. Such a profile has no password at all: it never went through the initial-credential handover an admin does when creating an account, so it does not answer to the default password. Sign-in goes through the provider, or an admin sets an explicit password from Settings > Admin Tools > User Management.
6. If POZNOTE_OIDC_DISABLE_NORMAL_LOGIN=true, the username/password form is hidden and the login page becomes SSO-only.
7. REST API clients can authenticate with Authorization: Bearer <OIDC JWT> when OIDC is enabled; Poznote validates the provider JWKS, issuer, expiration, audience, and configured access controls.
8. Clients that cannot perform an OIDC flow at all (browser extension, mobile app, scripts) use an app password instead, which each user creates from their own settings.
9. Two-factor authentication only covers the password form: an SSO login never asks for the Poznote code. Require a second factor in the identity provider instead. A user who has both a password and an SSO identity keeps both ways in, and the SSO one is only as strong as the provider's policy.

Configuration

OIDC is configured from the admin UI: go to Settings > Admin Tools > OIDC / SSO.

Most settings (enabled, issuer, provider name, scopes, access control, allowed groups/users, auto-create users, HTTP Basic Auth behavior, etc.) are managed from this page and stored in the database.

For REST API Bearer JWT authentication, configure API JWT audience if your provider issues access tokens for a dedicated API audience. When it is empty, Poznote accepts the configured OIDC Client ID as the JWT audience.

The following settings remain in the .env file:

POZNOTE_OIDC_CLIENT_ID=your_client_id
POZNOTE_OIDC_CLIENT_SECRET=your_client_secret
POZNOTE_OIDC_DISABLE_NORMAL_LOGIN=false

Use POZNOTE_OIDC_DISABLE_NORMAL_LOGIN=true if you want to hide the local username/password form and force SSO-only login. This is the only switch that blocks password authentication: it removes the form, rejects password POSTs server-side, and hides the "Change Password" setting.

Recovering from an identity provider outage. SSO-only means exactly that: while POZNOTE_OIDC_DISABLE_NORMAL_LOGIN=true, nobody can sign in with a password, admins included, so there is no in-browser escape hatch. This is deliberate, since an attacker who compromised an admin account cannot re-enable password login to give themselves a persistent way in. Recovery needs server access: set POZNOTE_OIDC_DISABLE_NORMAL_LOGIN=false in .env, restart the container, and sign in with a local password. Before enabling SSO-only, make sure at least one admin account has an explicit password set (Settings > Admin Tools > User Management), otherwise flipping the flag back will not help. Note that an admin profile auto-provisioned by OIDC has no password until one is set.

Breaking change: previous OIDC settings in .env are no longer read, except POZNOTE_OIDC_CLIENT_ID, POZNOTE_OIDC_CLIENT_SECRET, and POZNOTE_OIDC_DISABLE_NORMAL_LOGIN. After upgrading, re-enter the other OIDC settings from the admin page.

URLs to register with your identity provider

When you create the application (client) in your identity provider, register the first URL below as the redirect URI (also called callback URL), and the second one as the post-logout redirect URI if your provider asks for it:

https://YOUR_SERVER/oidc_callback.php
https://YOUR_SERVER/login.php

Poznote builds both from the host name the request arrives on, always with https://. If your provider needs something else, set Redirect URI or Post-logout redirect URI in the Advanced section of the OIDC admin page, and register that exact value.

The discovery URL does not usually need to be filled in: Poznote appends /.well-known/openid-configuration to the Issuer URL. With Authentik, for example, the issuer is https://AUTHENTIK_HOST/application/o/APPLICATION_SLUG/. Set Discovery URL only if your provider publishes that document somewhere else.

Access Control Example (Groups + Auto-Provision)

From the OIDC admin page, configure:

• Groups claim: groups
• Allowed groups: poznote
• Auto-create users: enabled

If auto-provisioning is enabled, Poznote generates a username from the OIDC claims (preferred_username, nickname, email local part, name, then sub) and stores the OIDC subject on the created profile. If an existing profile that has never signed in with SSO already carries that preferred_username, the login is refused instead of creating a second profile next to it: give that profile the email the provider sends, or its OIDC subject, so it is linked.

App Passwords

Apps cannot sign in through an identity provider the way a browser can. An app password is a separate credential you create for one client (the browser extension, a phone, a script) and can revoke at any time, so you never have to hand out your account password.

Create one from Settings > App passwords: give it a name, optionally an expiry, and copy the generated secret. It is shown once and never again. Then, in the client, enter your usual username and the app password where it asks for a password. It travels as ordinary HTTP Basic Auth, so every existing client works as-is:

curl -u 'username:pzn_2f7c…' https://YOUR_SERVER/api/v1/notes

An app password only reaches the REST API, and only for its own profile: it cannot open the web interface, call an admin endpoint, change your password or manage your account, even when the account is an administrator. A leaked one therefore exposes the notes of one account and nothing more, and revoking it closes the hole. On an SSO-only instance, where accounts created by OIDC have no password at all, it is the only credential the API accepts over Basic Auth.

The full list of limits and the endpoints that manage app passwords are in the REST API documentation.

Note types

Poznote has several note types, each tailored for a different way of working. Rich text and Markdown are the two note formats; the others below build on them.

• Editor: Direct WYSIWYG (What You See Is What You Get) editing.
• Storage: Saved as .html files in the user data directory. Since they are standard HTML, they can be opened directly in any web browser.
• Exclusive Features:
  • Rich Formatting: Native support for text colors, highlighting, and standard HTML elements.
  • Interactive UI: Direct manipulation of elements in the editor.

• Editor: Markdown syntax editor with real-time preview.
• Storage: Saved as .md files in the user data directory.
• Exclusive Features:
  • Mermaid Diagrams: Native support for generating diagrams (flowcharts, sequence, etc.) via ```mermaid code blocks.
  • Math Equations: Robust LaTeX support for mathematical formulas using $ inline $ and $$ block $$ syntax.
  • Portability: Standard Markdown format compatible with any external editor or static site generator.

• Usage: Manage tasks and projects with interactive checklists.
• Workflow: Track progress with checkboxes that can be toggled directly in the editor or the notes list. A progress bar shows the completion of each list.
• Task Options: Each task can have a due date with an optional time, a reminder notification that fires at the due time, and a priority (high, medium or low, shown in red, orange or green), and can be moved to another list.
• Tasks Page: A dedicated Tasks page, opened from the left icon rail, gathers in one place every task of your task lists and, optionally, the checkboxes sitting inside ordinary notes. It offers status filters (to do, high, medium or low priority, overdue, with due date, completed), a text filter, and a calendar view of the tasks that carry a due date. A task list, or the checkboxes of a note, can be hidden from the page with the eye button of its header and brought back with Show hidden lists. The choice is saved in your account, so it follows you from one device to the next.
• Public Collaboration: Task lists can be shared via a public URL. If edit permissions are granted, external collaborators can check items off the list without needing a Poznote account.

• Functionality: Create a reference to an existing note in another location.
• Use Case: Allows a note to be referenced in two different places simultaneously. For example, a note can live in a classification folder while its shortcut appears on a Kanban board for active tracking.

• Functionality: Reuse pre-written content to standardize your documentation, from a full note to a short snippet.
• Setup: Put the notes you want to reuse in a folder named Templates (sub-folders are fine). A workspace named Templates works too and is offered from every workspace. The name is also recognized in the language of the interface (Modèles, Vorlagen, Plantillas, Modelos, Шаблоны, 模板, 템플릿, テンプレート, Plantilles).
• Insert into a note: Type /template (or / followed by the template's title) in a rich text or Markdown note and pick a template: its content is pasted at the cursor, converted if the template and the note are not of the same type.
• New note from a template: Duplicate the template note, or duplicate a whole Templates folder to start a project with a ready-made folder structure.

• Usage: Write one note per day, journal-style, from a dedicated Diary board.
• Workflow: The "Create today's entry" button creates today's note (it reads "Go to today's entry" once the note exists), titled with the current date and stored automatically in a Diary/YYYY/MM folder structure.
• Another Day: The calendar button next to the view controls picks any day, on phones too. Days that already have an entry are marked with a dot; picking one opens its entry, picking another day creates the entry for that date.
• Board View: Entries are displayed as cards grouped by month, newest first, with a filter to quickly find past entries.
• Journal View: The scroll button next to the view controls switches to one reading column: every entry with its full content, newest first, loaded as you scroll. The filter works there too. Click an entry, or its pencil, to edit it right there; changes are saved as you type. The tag button next to the pencil turns the entry's tags into an editor: add or remove tags without opening the note.
• Format: New entries are created as rich text or Markdown notes, depending on the "Diary entry format" setting under Settings > Diary.
• Template: To start every new entry with the same content (headings, checkboxes...), keep that note in a folder named Templates of the workspace and pick it in the "Diary entry template" setting under Settings > Diary. Each workspace has its own template, chosen among its own notes: open Settings from the workspace to set it. The template is converted when its format differs from the entry's.

Revisions

Revisions keep earlier versions of a note's content, along with its title and tags, so you can compare them with the current note and go back to a previous state. The history icon in the note toolbar opens the note's Revisions page.

• History: the left column lists the note's revisions grouped by day, each one labeled Automatic, Manual, Before AI edit or Before MCP edit. A "Current" badge marks the revisions identical to the current note, and "No change" those identical to the revision before them. Both badges also require the same title and tags.
• Content: the page opens on this tab, which shows the selected revision itself, rendered. For Markdown notes, a Preview/Source switch sits next to the tabs.
• Changes: the second tab shows a line-by-line diff, with the changed words highlighted, against the current version, the previous revision or any other revision. The diff is shown Unified or Side by side, unchanged lines are folded (click to expand them), the previous and next change buttons jump from one change to the next, and the added and removed lines are counted. Markdown notes are compared on their source. Rich-text notes are compared on their text, so a change of formatting alone does not show. Above the diff, the tab shows the title change (old → new) and the tags added or removed between the two compared versions.
• Actions: the "Actions" menu holds "Restore this revision", "Save a revision", "Copy content" and "Delete this revision". "Save a revision" saves the current content right away, the other entries act on the selected revision.
• Restoring: a restore gives the note back the content, the title and the tags of the revision. The state it replaces is not saved: if it matters, save a revision first ("Save a revision" in the Actions menu, or Ctrl + Alt + S). A restored title follows the rename rules: if another note of the same folder already has that title, a suffix such as "(1)" is added. A revision saved before tags were recorded has no tags and leaves the note's tags untouched.

• Automatic: Poznote saves a revision when a note is modified, not when it is opened. Each time a change to the note's content, title or tags is saved (the editor's autosave, a task ticked, a drawing saved, the REST API, an edit from a public share link), Poznote first keeps the note as it was just before that change, unless a revision of that note was already taken in the last 10 minutes. A revision therefore always holds the state before a change, and an editing session produces at most one automatic revision every 10 minutes. Opening or reading a note never creates a revision. Nothing is saved for an empty note, nor when the newest revision already holds exactly the current content, title and tags, so the history has no duplicates. These revisions are labeled "Automatic" in the history, and so are the revisions that older versions of Poznote took when a note was opened: they follow the same rules.
• Example: you edit a note from 9:00 to 9:35. The history gets revisions at about 9:00 (the note before you touched it), 9:10, 9:20 and 9:30. You come back at 14:00 and change one word: a 14:00 revision keeps the note as you left it at 9:35.
• What you can go back to: the state you leave a note in at the end of a session is not saved as a revision at that moment, because it is the note itself. It is captured by the first change of the next session, however much later that is. So you can always return to how the note was before you started editing today, and, within a long session, to states at most about 10 minutes apart. The latest state is always the note itself: compare any revision with "Current version" to see what has changed since.
• How long automatic revisions are kept: every automatic revision of the last 24 hours is kept. Beyond 24 hours, only the most recent automatic revision of each day is kept, for 30 days by default. This number of days can be changed under Settings > Revisions (1 to 30). If you had already changed this setting in an older version, where it counted revisions, your value is kept and now counts days.
• Manual: "Save a revision" adds a revision at any time, and so does Ctrl + Alt + S (Cmd + Alt + S on Mac) while a note is open. Manual revisions are unlimited and never thinned out: they only go away when they expire, after 30 days.
• Before an AI edit: a revision is saved automatically right before the AI assistant or the MCP server changes the content of a note, even when an automatic revision was taken less than 10 minutes earlier, so a rewrite that goes wrong is one click away from being undone. These revisions are labeled "Before AI edit" or "Before MCP edit" in the history and are skipped when the latest revision already holds the same content, title and tags.
• Safety revisions: the "Before AI edit" and "Before MCP edit" revisions share one limit: the 20 most recent are kept per note, a number you can change in Settings → Revisions (1 to 200) if your instance edits a lot of notes through AI or MCP.
• Expiry: every revision, whatever its kind, is deleted 30 days after it was saved. A revision can also be deleted by hand from the Revisions page.
• Attachments and images: revisions store the note's text, title and tags, never its files. Attachments are never copied, so a file referenced by several revisions exists once on disk. A file removed from a note stays on disk, hidden from the note, as long as a revision still contains it, so restoring that revision brings it back. It is deleted for good once the last revision containing it expires or is deleted, or when the note is permanently deleted. Keeping more revisions therefore never duplicates files. It only keeps removed files around for longer, 30 days at most.
• API and MCP: the REST API and the MCP server tools still call revisions "snapshots" (/notes/{id}/snapshots, list_snapshots, get_snapshot, restore_snapshot).

Personalization

Poznote offers several built-in personalization options directly from the application, without requiring any configuration file changes.

The Settings page is split into sections, each one holding the cards that belong to it:

• Display: the app font, the size of the text and of the icons, the palette offered when colouring a note, the title of the login page.
• Element visibility: hide the interface elements you do not use, see below.
• Sidebar: the order and the colors of the buttons of the left icon rail (a right-click on one of them opens the color picker too), the note age filter, where the notes without a folder are listed, the dimming of the folders you are not working in.
• Note content: the width of the note, attachment previews, the default image border, where a new task is inserted, code blocks, attachments and backlinks at the bottom of a note, spell check, the command menu shortcut, the place of the formatting toolbar.
• Markdown: the default view mode, the views the view button of a note goes through (live preview, rich text, split), the editor font, framed and coloured Markdown.
• Diary: the format, the template and the date format of new entries.
• Sync & history: Git Sync, the offline notes, and how long revisions are kept (one automatic revision per day beyond the last 24 hours, and the safety revisions per note).
• My Account: the interface language, the timezone and the date format.

The theme is not a card here: the button at the bottom of the left icon rail walks through the themes, and an administrator chooses which ones it offers in Settings > Admin Tools > Theme list.

You can set a background image per workspace: open Settings > Workspaces and use the Background action of the workspace to upload an image and adjust its opacity, so each workspace gets its own visual identity.

Poznote allows you to declutter the interface by hiding elements you don't use.

Configure it in Settings > Element visibility.

• Granular Control: Toggle visibility for home cards, toolbar actions, slash menu items, and more. The creation date badge on notes (Show creation date) and the note count next to each folder (Show folder note counts) are turned on and off here too.
• Per-User: Each user can have their own unique interface layout.
• Administrators: The same modal shows a second "Users" column next to the administrator's own "Me" column, to hide elements for every user of the instance (administrators excepted).
• Searchable: Easily find the element you want to hide using the filter in the configuration modal.

Poznote ships with Inter and can use the fonts installed on your device. To use any other font, for instance a family from Google Fonts, an administrator uploads its files once and every user can then pick it.

Upload them in Settings > Admin Tools > Custom fonts, then choose the font in Settings > Display > App font or Settings > Markdown > Markdown editor font.

Notes:

• Accepted formats are WOFF2, WOFF, TTF and OTF, up to 10 MB per file.
• A family is several files (regular, bold, italic...) or a single variable font file. Select all the files of a family in one upload, they are grouped under the family name.
• The fonts are served by your own instance, nothing is loaded from Google or any other third party. Download the family first, from Google Fonts (Get font > Download all) or google-webfonts-helper.
• A family without a bold file keeps the default font for bold text and headings, so upload the bold file too.
• The files are stored in data/fonts/ (your Docker volume), so they survive image updates. Files copied there by hand are picked up when the Custom fonts dialog is opened.
• Each user chooses their own font. Deleting a family sends the users who had picked it back to the default font.
• Only administrators can upload or delete fonts.

If you want to adjust fonts, spacing, or other visual details beyond the built-in options, you can upload extra stylesheets that are applied to every HTML page for all users.

Configure them in Settings > Admin Tools > Custom CSS path.

Notes:

• Click Upload CSS file to select a .css file from your computer.
• Every uploaded file is kept, so you can store several themes and switch between them without uploading again.
• The modal lists what is stored: pick the one to apply to every user, or No custom CSS to go back to the built-in appearance, then click Save.
• Uploading a file that has the name of a stored one replaces that theme.
• The files are stored in data/css/ (your Docker volume), so they survive image updates.
• Click the bin icon next to a theme to delete that file from your volume.
• Poznote appends a cache-busting v= parameter automatically.
• The stylesheet is injected near the end of <head>, so it can override the default application styles.
• Only administrators can upload, apply or delete a custom CSS file.

The theme list

Settings > Admin Tools > Theme list says what the theme button at the bottom of the icon rail walks through: one theme per click, in the order shown.

• Tick the built-in themes you want to keep, and leave out the ones nobody uses.
• Tick a stored CSS file to offer it as a theme of its own. It gets a palette icon and the name of the file.
• Use the arrows to set the order the button walks through.
• A custom theme paints over a light or a dark base, which the file cannot say on its own: choose it next to the file. That is what data-theme is set to, so a stylesheet written for the dark mode needs Dark here.
• The list is a global setting, so everyone walks through the same themes; which one is applied stays each user's own choice.
• Whoever is on a theme you take out of the list gets the first theme of the list right away.
• Picking a custom theme loads that file for that user only, in place of the stylesheet applied instance-wide.
• Deleting a CSS file removes it from the list too.
• With a single theme in the list there is nothing to walk to, so the button opens this list for an administrator, and does nothing for everyone else.

Before writing any CSS, check whether a built-in theme already does what you want: the theme button at the bottom of the icon rail walks through Light, Dark, Black, Lavender, Sepia and Terminal.

Examples

Colours, spacing, radii and font weights are design tokens, so most changes are a short list of variable overrides rather than a fight with selectors. The full list is in src/public/css/tokens.css.

Change the accent colour

:root {
    --pz-accent: #d6336c;
    --pz-accent-hover: #a61e4d;
    --pz-accent-rgb: 214, 51, 108;   /* same colour, channels only, used for tints */
}
html[data-theme='dark'] {
    --pz-accent-text: #f783ac;       /* lighter, because it sits on a dark ground */
}

Two tokens rather than one because a fill and a label cannot be the same colour: --pz-accent fills buttons, --pz-accent-text is the accent as text, icons and outlines. In a light theme it follows --pz-accent by itself; a dark ground needs a lighter value. Every token keeps the same --pz-* name in every theme, only its value changes. The --dm-* names of older stylesheets keep working.

Recolour the note toolbar icons

.note-edit-toolbar .toolbar-btn i,
.note-edit-toolbar .toolbar-btn [class*="lucide-"],
.note-edit-toolbar .toolbar-btn:hover i,
.note-edit-toolbar .toolbar-btn:hover [class*="lucide-"] {
    color: #e5322d !important;
}

Icons are CSS masks painted with background-color: currentColor, so color is all you need. !important is needed here because a few of those icons already carry a colour of their own (the star when a note is a favourite, the share icon when it is published, the paperclip when it has attachments).

No CSS needed to colour a single icon: right-click it in the note toolbar or in the icon rail and pick a colour. Those colours are saved per user and leave the state colours above alone.

Warm up the whole interface

:root {
    --pz-bg: #f6ecd8;          /* page and note background */
    --pz-surface: #efe0c4;     /* panels, cards, menus */
    --pz-text: #3b2c1a;
    --pz-border: #d4bd94;
}

Write a full theme

Override the tokens on :root for light and on :root[data-theme='dark'] for dark, and nothing else. src/public/css/README.md documents every token and shows a complete example; the built-in Lavender, Sepia and Terminal themes in src/public/css/tokens.css are the same thing, written the same way.

Multi-users

Not to be confused with the Multiple Instances feature.

Poznote is multi-user: each profile has its own notes, workspaces, tags, folders, attachments and settings, and signs in with its own username or email address and password.

• User management: administrators create, disable and manage profiles from Settings > Admin Tools > User Management, and can give a user access to another user's account without transferring its ownership.
• Sharing and collaboration: workspaces, notes and folders can be shared with the other users of the instance, see Sharing and collaboration.
• Tenant isolation (SaaS mode): administrators can stop non-admin users from discovering the other accounts of the instance, sharing with them, or registering personal webhooks. Leave everything unchecked for a family or team instance.
• Local network access: non-admin users can only connect webhooks, Git Sync and their own AI, transcription or MCP servers to public internet hosts, apart from the local hosts an administrator allows, see Local network access for non-admin users.

Some features make the Poznote server itself connect to an address typed by a user: webhooks, Git Sync, and their own AI, transcription or MCP servers. The request leaves from the server, not from the user's browser. Without a limit, any account could use Poznote to reach the server itself, the other Docker containers, your local network or a cloud metadata service, places it cannot reach on its own.

So the rule depends on who typed the address:

• Administrators are not limited: they already control the server.
• Other users can only use public internet hosts. A local or private address is refused: localhost and 127.0.0.1, 10.x.x.x, 172.16.x.x to 172.31.x.x, 192.168.x.x, 169.254.x.x, local IPv6 addresses (fc00::/7, fe80::/10), and any name that points to one of them, such as the name of another Docker service.

What an administrator sets for the whole instance (the AI Assistant, Transcription, admin webhooks, S3, OIDC, SMTP) is not affected.

On a family or team instance, users may need a server on your network, for example an Ollama server for their personal AI or n8n for their webhooks. List those hosts in Settings > Admin Tools > Integrations > Local network access, one entry per line:

Entry	What it allows
ollama or ollama.lan	this host name, whatever address it points to (a Docker service name works)
*.home.arpa	every host name under this domain
192.168.1.20	this address
192.168.1.0/24	every address of this network (IPv6 works too, fd00::/8)

An entry allows every port of that host. Invalid entries are refused when you save, with the list of the ones to fix. The card shows Public only while the list is empty, and the number of entries otherwise.

Good to know:

• A host name in the list must resolve from inside the Poznote container, not only from your computer. A name that only your computer or your router knows cannot be resolved by Poznote, and it is refused like any unknown name: enter its address or its network instead.
• The address is checked again on every connection, not only when it is saved: removing an entry takes effect right away, and a name that later points to a local address is refused.
• For non-admin users, Poznote does not follow redirects, except in Git Sync, which checks every step of the redirect again.

Poznote uses a master database (data/master.db) for shared coordination data, and separate per-user databases and files for actual note content.

data/
├── master.db                    # Profiles, global settings, shared links, account access, edit locks
├── css/                         # Custom CSS files uploaded by an administrator
├── fonts/                       # Custom fonts uploaded by an administrator
├── backups/                     # Scheduled local backups, one folder per user ID
└── users/
    ├── 1/                       # User ID 1 (default admin)
    │   ├── database/poznote.db  # User's notes database
    │   ├── entries/             # User's note files (HTML/MD)
    │   ├── attachments/         # User's attachments
    │   ├── snapshots/           # Earlier versions of the user's notes (revisions)
    │   ├── backgrounds/         # Workspace background images
    │   └── backups/             # Backup archives prepared for download
    ├── 2/                       # User ID 2
    └── ...

Sharing and collaboration

Poznote offers several ways to work with the other users of your instance, each person keeping their own account. For a common space (family, friends, a team), share a workspace.

• Share a workspace: the owner opens Settings > Workspaces and clicks Share on the workspace's row (the share icon, or the first entry of its ... menu), then picks the users. They find the workspace in their own workspace menu, under Shared with me, and edit its notes and folders with the full editor, with the same write access as the owner. Next to each name, the owner can pick Read only instead of Can edit: that person then reads the notes, follows the changes live, opens the attachments and exports a note, and every write is refused, including through the AI assistant. The Dashboard, Tasks, Folders, Diary, Speed dial and Revisions pages, which edit as they go, are not available to them. The owner's other workspaces, settings, trash and backups stay private. In a shared workspace, writing @username in a note mentions that person, who finds it on their Mentions page. When the instance sends email (SMTP), each member can turn on Settings > Workspaces > Shared workspace emails to receive the list of notes the others created, edited or deleted there, a few minutes after the changes happen, or as a summary sent every day at 8:00 or every Monday at 8:00 (in the member's timezone).
• Share a note or a folder: Share in the note's menu, or in the folder's menu, creates a link to that note or folder alone. The link can be public, protected by a password, or restricted to some users of the instance, who sign in to open it, and it can allow editing. The Shares page of the icon rail lists your shares, and what the others shared with you under Shared with me.
• Give access to a whole account: an administrator can let a user open another user's account from Settings > Admin Tools > User Management, without transferring its ownership. The user switches to it from the Accounts section of the workspace menu.
• Editing the same note: one person edits at a time. A note that is only open for reading blocks no one: the lock is taken by the first change and given back after 15 seconds without changes. When a note is locked, the read-only banner offers to take over: the previous editor's screen turns read-only and their unsaved changes stay in their browser, offered again once the note is free. An open note picks up changes made elsewhere within a few seconds. For a Markdown note with unsaved edits on both sides, the two sets of changes are merged automatically when they touch different lines, and a banner lets you choose when they overlap. Rich-text notes are never merged, you choose which version to keep. Keep scripts and other code in fenced code blocks (```): raw HTML outside a code block is sanitized on save, which can make an otherwise clean merge look like a conflict.

Speed dial

The Speed dial view turns notes into a page of link tiles, made to be your browser's start page.

Give a note the speed-dial tag, or choose Add to speed dial in the menu of a note or a folder (for a folder, all its notes, subfolders included). Open the view with the lightning icon of the left icon rail.

• One link or none: the note is a tile that opens this link, or the note itself. Its icon is the first image of the note, otherwise the site's icon, otherwise the first letter of the title.
• Several links: the note is a group of tiles named after the note, with one tile per link. A horizontal line (----) starts a new row, and a link around an image uses it as icon: [![GitHub](https://example.com/icon.png)](https://github.com).
• Group name: a click opens the note, a right-click changes the color of its label.
• Several speed dials: New speed dial creates another one, and pills switch between them (for example Work and Home). Each one is a tag, such as speed-dial-Work, with its own background image. A right-click on a pill renames or deletes it: deleting keeps the notes. The menus of notes and folders then offer Add to a speed dial, with the list of speed dials beside it: a tick shows the ones they are on, and a click adds or removes.
• Arrange the view: drag tiles and groups to move them, and change their size with the button next to the filter. The ... menu at the bottom right sets a background image, and the eye button hides what you do not need.
• Browser start page: use speed_dial.php?workspace=Name&focus=1 after your Poznote address. focus=1 also hides the icon rail.

Activity Log

Poznote keeps a history of the sensitive operations performed on the instance, so administrators can see what happened, when, and by whom: logins and logouts, account and quota changes, workspace creation and sharing, backups and restores, trash emptying and permanent deletions, app passwords. It is available from Settings > Admin Tools > Activity log, restricted to administrators, and the help icon at the top of the page lists every recorded operation.

The log records that an operation happened, not the data it touched: note content and passwords are never written to it, and routine activity such as writing a note or moving it to the trash is left out. Entries are kept for 90 days by default (30, 90, 365 days or unlimited), and the log can be cleared from the same page.

Webhooks

Poznote can notify external services when something happens on the instance, by sending outgoing webhooks (HTTP POST requests with a JSON payload) to the endpoints you register, so it plugs into automation tools such as n8n, Zapier, or your own scripts. Administrators register instance events (accounts, quotas, signups) under Settings > Admin Tools > Admin Webhooks, and every user can register endpoints for their own notes and reminders under Settings > User Webhooks.

Deliveries are signed with HMAC-SHA256 when the webhook has a secret, and note content is never sent. Every event, the payload fields, signature verification and delivery guarantees are covered in the Webhooks documentation.

Git Synchronization

Poznote supports automatic and manual synchronization with GitHub, GitLab (gitlab.com or a self-hosted instance) or Forgejo. Each user configures their own repository independently. There is no shared global repository.

Git Sync talks to the provider's REST API over HTTPS, so authentication is always token-based. SSH keys are not used.

Step 1 — Enable the feature (admin, in Settings > Admin Tools)

Toggle Git Sync to enabled in the Admin Tools section of the Settings page. This enables Git Sync globally and makes the user-level Git Sync card/configuration available from Settings.

---

Step 2 — Each user configures their own repo (Settings > Git Sync)

Field	Description
Provider	GitHub, GitLab or Forgejo
API Base URL	GitHub: auto-filled (read-only). GitLab: https://gitlab.com/api/v4, or your instance URL, e.g. https://gitlab.example.com/api/v4. Forgejo: your instance URL, e.g. https://forgejo.example.com/api/v1
Access Token	GitHub PAT (ghp_...), GitLab token with the api scope (glpat-..., personal or project access token) or Forgejo token (Settings > Applications)
Repository	owner/repo format. GitLab: the full project path, including subgroups, e.g. group/subgroup/project
Branch	Default: main
Author Name / Email	Used for commit metadata

🔒 Access tokens are encrypted at rest using AES-256-GCM. An encryption key is automatically generated and stored in data/.app_secret.

---

Automatic sync

When enabled by the user, Poznote will automatically:

• Pull on login
• Push on every note create, update, or delete

Manual push/pull is also available from the Push and Pull buttons of the left icon rail.

---

Synced workspaces

By default every workspace is synced. In Settings > Git Sync, each user can instead restrict Git Sync to selected workspaces:

• Only notes and attachments from the selected workspaces are pushed and pulled.
• A pull never touches notes in the other workspaces.
• A push removes repository files that fall outside the selected workspaces, so the repository always mirrors exactly the synced set.
• The Push and Pull sidebar buttons, automatic push, and the pull prompt only appear while viewing a synced workspace.

S3 Attachment Storage

By default, note attachments are stored on the local disk. Administrators can instead store them in an S3-compatible object storage (AWS S3, MinIO, Garage, Cloudflare R2, Backblaze B2, ...). The setting applies to all users of the insta