Installation (macOS)

Truetask ships as a native macOS menubar app that bundles the database, API, MCP server, and reverse proxy into a single drag-installable .dmg. No Docker, no Terminal, no command line — fully offline once installed.

This page covers the macOS native install — the easiest path for a single user trialing Truetask on a laptop, or a small office running Truetask on a dedicated Mac.

Other install paths

• macOS native install — this page. Drag-install .dmg, menubar app
• Windows native install — .msi installer, system tray app
• Docker / Server install — for production, multi-user teams, or Linux servers

System requirements

Requirement	Minimum	Notes
macOS	14 (Sonoma)	14 or newer required
Architecture	Apple Silicon or Intel	Universal binary, runs natively on both
RAM	1 GB free	2 GB recommended
Disk	~500 MB	Plus storage for uploads and backups

Install

1. Download Truetask.dmg from the Truetask Client Portal.
2. Double-click the .dmg to open it.
3. Drag Truetask.app into the /Applications folder.
4. Eject the disk image and launch Truetask from /Applications (or Spotlight).

Truetask appears as an icon at the top-right of the macOS menubar. There is no Dock icon and no main window — everything lives in the menubar dropdown.

First launch and Gatekeeper

Truetask is currently distributed with ad-hoc code signing while Apple Developer ID notarization is being set up. On first launch macOS may refuse to open the app. To bypass: right-click Truetask.app in /Applications and choose Open, then confirm. This only needs to be done once.

First-run setup

On first launch a setup sheet appears asking you to create the Truetask admin account:

Field	Description
Admin email	The email you'll use to log into Truetask. Stored locally.
Admin password	Minimum 10 characters with uppercase, lowercase, and a digit.
Port (advanced)	Defaults to 8080. If the port is already in use, the Advanced section expands and you can pick a different one.

This account is local to your install

The admin account you create here is separate from any Truetask Client Portal credentials. It's the account you'll use to log into the Truetask web UI on this machine.

Once you confirm, Truetask starts the bundled server and opens your default browser to the local login page (e.g. http://localhost:8080). Your admin email is pre-filled — enter the password you just chose to sign in.

License activation

Trial signup at truetask.io sends a welcome email containing a truetask.lic file. To activate:

1. Sign into the Truetask web UI with the admin account from first-run.
2. Open Settings → License.
3. Upload the .lic file attached to your welcome email.

The license is verified locally — Truetask does not phone home to validate it.

Data and logs

Location	Path	Notes
Data	~/Library/Application Support/Truetask/	Database, uploaded files, config. Survives app updates and reinstalls.
Backups	~/Library/Application Support/Truetask/backups/	On-demand backups created via the menubar.
Logs	~/Library/Logs/Truetask/	Per-process: PocketBase, API, MCP, Caddy.

The menubar has an Open Data Folder action. An in-app log viewer is available under Settings → Logs.

For a guide to backup strategy and restore, see Backup & Recovery. The menubar provides a Backup Now action; restores happen through the same channel.

Settings overview

Open Settings from the menubar to access:

Tab	What it controls
General	Launch Truetask at login (off by default).
Network	Listening port; LAN sharing toggle.
Account	Admin email and password (Touch ID-gated reveal/reset).
Updates	Current version; manual update check.
Logs	In-app log viewer for all bundled processes.

LAN sharing

LAN sharing is off by default — the server binds to loopback only and is accessible only from the Mac it's running on. Toggle LAN sharing on under Settings → Network to let other devices on the same network reach Truetask. When on, the menubar displays the LAN URL (e.g. http://192.168.1.42:8080) for use on other devices.

Run-at-login

The "Launch Truetask at login" toggle in Settings → General registers Truetask with macOS so the menubar app and server start automatically when you log in. Off by default.

Watchdog

If any of the bundled processes (PocketBase, API, MCP, Caddy) exits unexpectedly, Truetask automatically restarts it up to 3 times within 60 seconds. If the process keeps failing past that threshold, Truetask stops trying and posts a macOS notification so you can investigate the logs.

Updates

The current Truetask version is shown under Settings → Updates.

Automatic updates coming soon

You can currently check for updates manually. Fully automatic background updates are still being finalized on the macOS side. When ready, Truetask will be able to download and install updates in the background with your consent.

Truetask contacts the portal only when you explicitly check for an update — never as background telemetry.

Uninstall

To completely remove Truetask, including all data:

1. Open Settings → Reset Truetask… from the menubar.
2. Confirm both dialogs. This wipes the local database, Keychain entries, and config.
3. Quit Truetask from the menubar.
4. Drag Truetask.app from /Applications to the Trash.

Reset is destructive

"Reset Truetask…" deletes your local database, uploaded files, and admin credentials. Take a backup first if you want to preserve any of it.