PTM Clearwork user manual

1. Overview

PTM Clearwork has three parts, and all of them run inside your own network:

• The server, which you start with Docker. It stores everything and serves the dashboard.
• The dashboard, a web page served by that same server, where you view employees, screenshots and activity.
• The desktop agent, installed on each employee machine, which captures activity and screenshots and reports live status.

Nothing leaves your server. Setting up means: start the server, create your admin login, then install the agent on each machine.

2. System requirements

• For the server: any machine with Docker and Docker Compose v2. That is the only prerequisite.
• For employee machines: Windows, macOS or Linux. The agent is small and sits in the system tray, so there are no special hardware requirements.
• Local testing on the server itself: plain HTTP at localhost is supported.
• Employee machines, LAN or internet access: use HTTPS in front of the server (your reverse proxy, cloud load balancer or Cloudflare). Packaged agents intentionally reject plain HTTP to a non-local server.

3. Deploy the backend & dashboard (Docker)

Deployment is zero-config. We provide a one-command installer (Linux & macOS) that manages a Compose file for you in ~/.ptm-clearwork, so there's nothing to copy and no secrets to generate. The server auto-generates its own per-deployment secrets on first boot:

# Download and run the installer
curl -fsSL https://cleanwork.ptmsoftware.live/install.sh -o ptm-clearwork
chmod +x ptm-clearwork
./ptm-clearwork start

Windows: download install.ps1, then run the following from the folder where it was saved:

Set-ExecutionPolicy -Scope Process Bypass
.\install.ps1 start

The server speaks plain HTTP on a single port and serves both the API and the dashboard. Verify it's healthy:

curl http://localhost:3124/api/v1/health
# → {"status":"ok","db":"connected","uptime":...}

For a public deployment, terminate TLS in front of the server (your reverse proxy, a cloud load balancer, or Cloudflare) and forward to its port - the app itself stays plain HTTP behind it.

4. Create the first admin user

You create the first admin right in the browser - no CLI needed:

1. Open the dashboard at http://localhost:3124/ptm-clearwork-dashboard/ (the bare / redirects there). On a fresh deployment it shows a "Create your admin account" screen.
2. Grab the one-time setup code the server printed to its logs on first boot:

   ./ptm-clearwork logs

3. Enter the setup code along with your name, email and password, then submit. You're logged in as the first admin.

5. Get the agent installer

You do not build anything. PTM Software supplies a ready installer for each platform you need:

• Windows installer (.exe)
• macOS disk image
• Linux AppImage, deb or rpm

Your installer links come with your trial or order email. If you do not have them, email hello@ptmsoftware.live and say which platforms you need.

6. Install on an employee machine

1. Run the installer and finish the wizard.
2. On first launch a setup window asks for Name, Work Email, an email-bound Enrollment code (from the admin), and the HTTPS Server URL. Click Register Device.
3. The agent redeems the enrollment code with the server, stores its API token in the OS keystore (encrypted), then relaunches into tray mode and configures auto-start at login.
4. Within seconds the device appears in the dashboard as Active - live, no refresh needed.

7. Using the dashboard

Sign in at http(s)://<host>/ptm-clearwork-dashboard/ (the bare / redirects there). From there you can:

• Dashboard - see live counts of who is Active, Idle and Offline, updated in real time.
• Employees - browse everyone, see live status badges, and open an individual to drill in. Select one or many to set monitoring hours.
• Activity & Screenshots - review captured activity timelines and the screenshot gallery for any employee.
• Productivity - see aggregated active vs. idle breakdowns over time.

8. Monitoring hours (working schedule)

By default the agent monitors whenever it's running. You can optionally restrict it to a working-hours window - outside it the agent fully pauses (no screenshots, activity or heartbeat) and shows Offline.

What a schedule is

• One or more windows, each with its own days plus a start and end time, evaluated in the employee's local machine time. The agent monitors when any window matches, so different hours per day, split shifts, weekend hours and overnight windows (e.g. 22:00-06:00) all work.
• No schedule = monitor at all times (the default).
• Changes are pushed to running agents in real time over the socket and apply immediately.

Set it from the dashboard (per employee or bulk)

1. On the Employees page, tick one or more employees (or the header box to select the page).
2. Click "Set monitoring hours".
3. Set the Start/End time, toggle the days, then Save hours - applied to everyone selected at once. Use "Turn off (monitor always)" to clear a schedule.

The Monitoring column shows each employee's current window - e.g. 09:00-18:00 - Mon-Fri or Always.

9. Data & retention

• Encrypted at rest. Screenshots and captured URLs are AES-256-GCM encrypted with your DATA_ENCRYPTION_KEY. Back that key up: without it the screenshots cannot be recovered.
• Automatic cleanup. SCREENSHOT_RETENTION_DAYS (default 90) deletes older screenshots for you.
• Back up these two Docker volumes: ptm-clearwork-mongo-data (accounts, employees, device identities and activity) and ptm-clearwork-uploads (screenshots, generated secrets and Install ID).

The two volumes are external, so docker compose down -v cannot remove them. Normal docker system prune, including --volumes, does not remove named volumes. A Docker administrator can still explicitly run docker volume rm, docker volume prune --all, reset Docker Desktop or erase the host disk—keep encrypted, off-host backups of both volumes.

docker volume inspect ptm-clearwork-mongo-data ptm-clearwork-uploads

The full picture, mechanism by mechanism, is on the security page.

10. Trial & licensing

After first boot, copy the displayed Install ID and request a vendor-issued 7-day trial key. The emailed key works only on that deployment and covers up to 15 employees.

• Before and after a trial. The dashboard asks for a trial or licence key. Your data is untouched and agents keep running and buffering, so nothing is lost while you sort out a key.
• Activating a key. Paste the emailed trial or licence key into the dashboard when prompted. A paid key can also be set as LICENSE_KEY and activated on restart.
• Seat limits are enforced: Starter 15, Business 75, Enterprise unlimited. At the limit, new agents cannot enrol until you free a seat. Deactivating someone who has left frees their seat and keeps their history.
• No internet needed. Keys are cryptographically signed and verified locally, so licensing works on an isolated network and never calls home.
• Tied to your deployment. Your licence screen shows an Install ID, and every key is locked to it. It survives container recreates, host reboots and IP changes; a full data wipe creates a new ID and needs a newly issued key.

11. Uninstalling the agent (all OSes)

The agent leaves three things on a machine: the app, its data folder (encrypted token, logs, activity buffer), and an auto-start entry. Removing all three is a complete uninstall. Quit the running agent first (tray icon → Quit).

App identifiers: product name PTM Clearwork, app id com.ptm.clearwork.

Windows

# Quit, then uninstall via Settings → Apps → "PTM Clearwork"
Stop-Process -Name "PTM Clearwork" -Force -ErrorAction SilentlyContinue
# Clean up leftovers (PowerShell)
Remove-Item -Recurse -Force "$env:APPDATA\PTM Clearwork" -ErrorAction SilentlyContinue
Remove-ItemProperty -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Run" -Name "PTM Clearwork" -ErrorAction SilentlyContinue

macOS

osascript -e 'quit app "PTM Clearwork"' 2>/dev/null; killall "PTM Clearwork" 2>/dev/null
rm -rf "/Applications/PTM Clearwork.app"
rm -rf "$HOME/Library/Application Support/PTM Clearwork"
rm -f  "$HOME/Library/Preferences/com.ptm.clearwork.plist"

Linux

pkill -f "PTM Clearwork" 2>/dev/null; pkill ptm-clearwork 2>/dev/null
sudo apt-get remove --purge ptm-clearwork    # .deb
sudo dnf remove ptm-clearwork                # .rpm
rm -f  "$HOME/.config/autostart/ptm-clearwork.desktop"
rm -rf "$HOME/.config/PTM Clearwork"

12. Troubleshooting

Server logs: ./ptm-clearwork logs. The agent log on a client machine lives at %APPDATA%\PTM Clearwork\agent_debug.log (Windows) or the equivalent app-support folder on macOS/Linux.

13. Configuration reference

Server environment

Agent (config.json or env override)