Cleanwork by PTM user manual

Overview

Cleanwork by PTM monitoring has three parts. In a self-hosted deployment, you operate these components; the customer portal and billing services are separate:

• 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.

Monitoring stays in your deployment by default; optional object storage, portal, billing and website assistant services have separate data flows. Setting up means: start the server, create your admin login, then install the agent on each machine.

Features available today

Use this list when evaluating the current product. Availability depends on the supplied release, desktop permissions and your configured settings. A licence seat limit and a server's tested capacity are separate.

Compare Cleanwork with other products

Visit compare clearwork with other products on the pricing page for the current buying guide. Continue below for installation, daily use and troubleshooting.

Availability and future additions

Available now means the feature is listed above and included in your supplied release. Optional service means separately configured storage or a managed-hosting agreement; it is not an extra desktop feature. Future addition means an idea or plan that is not available for purchase as a working feature today.

SSO/SAML sign-in, automatic desktop updates, full Wayland/mobile monitoring and multiple application replicas are not available in the standard release. Do not make a purchase dependent on these capabilities without an agreed supported solution.

Future feature announcements will be listed separately once their scope is confirmed. No additional feature or delivery date is promised by this guide. Ask PTM about a requirement before purchase and check release notes before enabling a newly delivered feature.

How many server instances?

For a standard self-hosted deployment, buy one always-on server instance. The supplied installer places the dashboard and its required data services on that server. Employees do not each need a cloud instance. There is no separate dashboard hosting charge. A single server has downtime during maintenance or a host failure.

Increase the resources of the existing server when the pilot shows it is too small. Running multiple copies of the application is not supported by the standard deployment. For more than 250 devices or a requirement for uninterrupted availability, ask PTM to review the deployment before you purchase infrastructure.

An employee-seat license is separate from compute capacity. An unlimited-seat plan does not make one server unlimited. A managed subscription's hosting, backups and uptime responsibilities must be confirmed in the PTM order; self-hosted customers operate their own infrastructure.

These are starting estimates, not guaranteed employee capacities. Team size, image sizes, monitoring hours and report usage affect the result. Keep at least 30% free disk space and monitor memory and CPU during a working-week pilot.

Hosting choices and monthly cost

Visit hosting choices and monthly cost on the pricing page for the current buying guide. Continue below for installation, daily use and troubleshooting.

Calculate storage and bandwidth

Measure average compressed screenshot size during a pilot. Example assumptions: 100 KB per screenshot, eight monitored hours/day, one capture/minute, 90 retained calendar days, work every day. Actual images vary. This deliberately assumes every scheduled capture occurs.

Adjust for your team: start with 4.32 GB per device for the assumptions above. Multiply by your device count. If your average screenshot is 300 KB instead of 100 KB, multiply storage and upload bandwidth by three. If you retain 30 days instead of 90, divide storage by three; this does not reduce live upload bandwidth. If your configured capture interval is five minutes instead of one, divide both by five.

Add OS, database records/indexes, logs, encryption metadata and backups, then keep at least 30% free headroom. The screenshot totals exclude the operating system, activity history and backups. Galleries add outbound traffic. Allow for bursts after login and recovery. Idle/off-hours reduce capture, but should not be relied on for a hard disk limit.

Activity history does not share screenshot retention and continues to grow separately. Measure database growth over a full working week and set a separate history policy with your operator. External object storage reduces local image disk use, not database growth or server network traffic.

Setup at a glance

Setting up has two parts: the server first, then each employee computer. Follow the steps in order; each title opens its full instructions.

Part A: the server

1. Check the requirements

   An always-on computer with Docker and Docker Compose v2.

2. Start the server

   Paste one command. It downloads the images and starts everything.

3. Activate it and create the first admin

   Enter your account email and the setup code PTM emailed you.

4. Put HTTPS in front of it

   Needed before employees connect over a network. Skip it for a test on the same computer.

Part B: each employee computer

1. Get the agent installer

   PTM sends a ready-made installer for each platform.

2. Approve employee enrollment

   Share the server address, work email and any enrollment code required by your matched release.

3. Install the agent

   Windows, macOS or Linux. Then confirm the device shows up in the dashboard.

Finished with Cleanwork? Removal has its own section, kept apart from setup.

System requirements

• Server: one always-on computer with Docker and Docker Compose v2 installed. See how many server instances? for sizing.
• Don't have Docker yet? Paste the install command in step 2 anyway: it checks for Docker and, if it is missing, explains exactly how to get it. On Windows it can install Docker Desktop for you (once WSL 2 is on), on Linux it offers Docker's official install script, and on macOS it tells you what to download. Manual guides: Windows, macOS, Linux. Docker Desktop needs 64-bit Windows 10 21H2 or newer, 4 GB of memory and WSL 2.
• Employee computers: Windows, macOS or Linux. See the table below for what each needs.
• Testing on the server itself: plain HTTP on localhost works fine, no extra setup needed.
• Employees connecting over a network or the internet: put HTTPS in front of the server first (see HTTPS and deployment settings). The desktop agent refuses to connect over plain HTTP to anything other than localhost.

Supported platforms

Run the server on an always-on Linux machine with Docker and Docker Compose v2. For a quick test, Docker Desktop on Windows or macOS works too. Before buying hosting, check with PTM that the server supports your CPU type - a Mac or ARM employee installer does not mean the server itself runs on ARM.

Install the agent on one test device per platform first, grant the permissions it asks for, and confirm screenshots and activity show up before rolling it out to everyone.

On Debian/Ubuntu Linux, install these helper packages first:

sudo apt-get update
sudo apt-get install imagemagick x11-xserver-utils xdotool python3 python3-gi gir1.2-atspi-2.0

Package names vary on other distributions. Also make sure a keyring app (GNOME Keyring or KWallet) is unlocked, and restart after installing the helpers. Some browsers still won't report their URL even with everything installed - test that separately from the rest of activity tracking. Run the agent as the employee's own signed-in user, not as root or a background service; it starts automatically the next time they log in, not before.

Set up your server

Paste one command below and it does everything: downloads the installer, creates the data storage, pulls the images and starts the server - no files to copy and nothing to configure first. You'll still want to add HTTPS and set up backups before going live; see the sections below for that.

Linux & macOS - open a terminal and run:

curl -fsSL https://cleanwork.ptmsoftware.live/install.sh -o ptm-clearwork && chmod +x ptm-clearwork && ./ptm-clearwork start

Windows - open PowerShell and run:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force; irm https://cleanwork.ptmsoftware.live/install.ps1 -OutFile install.ps1; if ($?) { .\install.ps1 start }

That's it - the command saves itself in the current folder (so stop, update, logs, status and uninstall keep working later, see Remove the server) and finishes with the dashboard already running. Nothing else to type. If Docker is not installed, the command stops and tells you how to get it (it can install it for you on Windows and Linux); paste the same command again afterwards and it continues. If Docker Desktop is installed but not open, the command starts it and waits for it. If the download fails (for example The remote name could not be resolved, which means a DNS or network problem on your side), nothing runs; check your connection and paste the same command again.

Check that it's running:

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

The server itself only speaks plain HTTP. That's fine for testing on localhost - for real employee use (over a network or the internet), put HTTPS in front of it first, see HTTPS and deployment settings (step 4).

Open the dashboard from other computers on your network

Out of the box only the computer running Docker can open the dashboard: the installer binds the server to 127.0.0.1, so a laptop on the same Wi-Fi gets "connection refused". To open it from any computer on your network, start it once with the bind address set. The setting is saved, so later start and update runs keep it, and the installer prints the address other computers should use.

# macOS / Linux
BIND_ADDRESS=0.0.0.0 ./ptm-clearwork start
# Windows PowerShell
$env:BIND_ADDRESS = "0.0.0.0"; .\install.ps1 start

Then open http://<server-ip>:3124/ptm-clearwork-dashboard/ from the other computer (find the IP with hostname -I on Linux, ipconfig on Windows or in System Settings → Network on macOS). This is plain HTTP on your local network: fine for looking at the dashboard and trying the admin flow, but employee agents only connect to https:// addresses (or to localhost on the same machine), because they carry screenshots and device tokens. Before enrolling real devices, give the server an HTTPS address as described in step 4, and set BIND_ADDRESS=127.0.0.1 again so only the proxy can reach the plain-HTTP port.

PTM-hosted workspace: what happens after you buy

If you chose a cloud plan on the pricing page, there is nothing to install. PTM builds a private server for your organisation and you use it from the browser. Here is the whole journey, so you know what to expect and when.

1. Checkout

   You pick your organisation name (for example acme), which becomes your address https://cw-acme.ptmsoftware.live, accept the hosting terms, and pay with the provider. The address is reserved the moment you submit.

2. Two emails arrive

   First your setup code (CW-XXXX-XXXX-XXXX-XXXX), as soon as payment is confirmed and your email is verified. Then "We are preparing your workspace", which names your address. Building the server usually takes under an hour; your customer portal shows live progress.

3. "Your workspace is ready"

   This email has the two links you need: your dashboard (https://cw-acme.ptmsoftware.live/ptm-clearwork-dashboard/) and the server address for employee devices (https://cw-acme.ptmsoftware.live). Both also appear in your portal.

4. Create your administrator

   Open the dashboard link, enter the email you bought with and the setup code, choose a password. That is your admin sign-in from now on; the code is used up.

5. Enrol employees

   In Employees → Enroll device create a one-time enrollment code per person. They install the desktop agent and enter their work email, the code and the server address. Their activity shows within a minute.

What you get: a dedicated machine nobody else shares, private encrypted screenshot storage, HTTPS already configured, and seven daily database backups while your plan is active. Billing: monthly, cancel any time from the portal; access continues to the end of the paid period, then the workspace is suspended. Your data is kept while suspended and deleted only when you ask us in writing. If something goes wrong while we build the server, you get an email, our team is alerted automatically, and you owe nothing extra; your address and plan are kept.

Activate and create the first admin

One setup code activates your server and creates your first admin account:

1. Buy a plan or start an eligible trial from pricing. Trial verification may include a small refundable authorisation amount; plan billing starts after the trial. After provider confirmation, PTM emails a setup code (CW-XXXX-XXXX-XXXX-XXXX) to your account email. If you have not verified that email yet, the code is sent when you do.
2. Open the dashboard at http://localhost:3124/. A fresh install shows the "Activate Cleanwork by PTM" screen.
3. Enter the email the code was sent to, the code, your name and a password. The server activates itself with PTM and signs you in as the first admin. That email becomes your admin sign-in.

Lost or expired code? Sign in to the customer portal and choose Email me a new setup code. Codes last 7 days, work once, and a new code cancels the previous one.

HTTPS and deployment settings

Remember: localhost always means "this same computer" - an employee's own localhost is never your server. For real use, pick a domain like https://monitor.example.com and put a reverse proxy (nginx, Caddy, Traefik, or a cloud load balancer) in front of the server to handle HTTPS. Point the proxy at the server's port, and make sure it forwards the dashboard, /api/ and /socket.io/ paths, allows WebSocket connections, allows uploads a bit larger than 5 MB, and doesn't time out before 30 seconds.

The installer keeps its files in ~/.ptm-clearwork (Windows: %USERPROFILE%\.ptm-clearwork). Don't edit compose.yaml by hand - it gets rewritten every time you run start or update. Instead, add settings to the .env file in that same folder, then run start again to apply them. If you have exactly one reverse proxy in front of the server, add:

TRUST_PROXY=1
CORS_ORIGINS=https://monitor.example.com
SCREENSHOT_RETENTION_DAYS=90
BIND_ADDRESS=127.0.0.1

BIND_ADDRESS=127.0.0.1 is the installer's default and keeps the plain-HTTP port private to the proxy on the same machine. Set it to 0.0.0.0 only for a network trial without HTTPS (see step 2), or when the proxy runs on a different machine - in that case restrict port 3124 to the proxy's address with your firewall.

A few safety rules: your proxy must overwrite (not just append to) forwarded-IP headers, so nobody can fake their address. If you also use a CDN, get help checking the trust settings. Never expose MongoDB to the internet, and never disable TLS certificate checking as a "quick fix."

Only the settings above are supported - check with PTM before changing anything else. After any change, run start again and confirm employees can still connect.

Get the agent installer

Get the ready-made Windows, macOS or Linux installer from the Downloads page. Choose your operating system and CPU type; macOS also offers a universal installer for Intel and Apple silicon. Review each build's signature status before installing. Available installer formats include:

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

If your platform is not available on the Downloads page, use the installer link in your trial or order email, or email hello@ptmsoftware.live with your operating system and processor type.

Employees and account details

In Employees → Enroll device, enter the employee's work email and create an enrollment code. Share the code, the HTTPS server address and the matching installer privately with that employee. Each code is bound to that email, expires after 24 hours and can register one device.

A replacement code cancels earlier unused codes for that employee. Revoke an unused code if it was shared incorrectly. Creating a new employee reserves a licensed seat; revoke the invitation and block the employee to free an unused seat. A blocked employee cannot redeem an invitation.

Your dashboard login and PTM customer-portal login are separate accounts. Employees need their own email, server address and enrollment code; they never need your administrator password. Existing registered devices keep their device tokens when the server is upgraded.

When someone leaves, block them on the Employees page (not just uninstall the app) - that stops monitoring and frees their seat immediately while keeping their history, and a blocked person cannot register again. Remove deletes the employee and all of their activity, sessions and screenshots for good, and disconnects their agent.

Install on an employee machine

The installer file and first steps differ by OS. All three finish at the same setup window - see Finish setup (all OSes) below.

Windows (.exe)

1. Download the matching .exe installer from the Windows downloads and run it.
2. If Windows shows "Windows protected your PC" (SmartScreen), click More info, then Run anyway. This can appear the first time a new release is installed.
3. Approve the administrator prompt and finish the wizard. It launches the app automatically.

macOS (disk image)

1. Open the downloaded .dmg, then drag PTM Clearwork into Applications. Existing installers retain this application name for compatibility. Eject the disk image afterwards.
2. First launch only: if macOS shows "cannot be opened because the developer cannot be verified", right-click (or Control-click) the app in Applications, choose Open, then confirm Open in the dialog. This bypass is only needed once per machine.
3. When prompted, grant Screen Recording, Accessibility/Input Monitoring, and Automation (for the browsers you want URL tracking on) under System Settings → Privacy & Security. Quit and reopen the app after granting any of these - macOS does not apply them to an already-running process.

Linux (AppImage, deb or rpm)

Install the capture helpers first if you haven't already, then install the package that matches your distribution:

# AppImage - make it executable, then run it
chmod +x PTM-Clearwork-*.AppImage
./PTM-Clearwork-*.AppImage

# .deb (Debian/Ubuntu)
sudo apt install ./ptm-clearwork_*.deb

# .rpm (Fedora/RHEL)
sudo dnf install ./ptm-clearwork-*.rpm

Launch it from your desktop's application menu (or run ptm-clearwork from a terminal) in the employee's normal graphical login session - not as root and not over SSH/headless.

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.

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 and apply when received.

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.

Configure activity tracking

Open Settings → Activity tracking in your local dashboard. Track browser URLs and Track application usage control those two collection features across the deployment. Toggle changes save immediately and are pushed to connected agents; reconnecting agents refresh settings from the server.

Set the URL and application check frequencies in seconds, then select Save frequency. Each value must be between 5 and 600 seconds; an empty override uses the agent default (URL: 30 seconds, application: 15 seconds). Shorter intervals increase sampling and processing. These controls do not change screenshot frequency or monitoring hours. Verify a connected pilot device after each change and explain collection changes to employees.

Configure screenshot storage

Local storage is available with the supplied deployment. To use an S3-compatible bucket, open Settings → Storage destinations and connect a cloud storage profile. Have your storage administrator create a private bucket and credentials that can upload, read and delete objects in the intended prefix. Keep public access disabled.

Enter the profile name, provider, region, bucket and optional object prefix. For an S3-compatible service, use its S3 API endpoint, not a public bucket website URL. Cloudflare R2 normally uses region auto. Enter the access key, secret and optional session token; enable path-style addressing only when your provider requires it. Server-side endpoint protections can reject private or local addresses; ask your operator to review private-storage requirements before deployment.

Use Test connection, then Save profile, then choose Activate on the saved destination. Confirm a new screenshot uploads and opens in the employee gallery. A successful connection test does not verify long-term capacity or retention permissions under every provider policy.

Changing the active destination affects new uploads. Existing images remain associated with their original storage profile; keep its bucket and credentials available until its retained objects are removed. Saving a profile does not migrate old images. Credentials are encrypted on the server and not returned to the browser after saving; when editing, blank credential fields preserve the saved values. Back up external objects separately and include provider storage, request and transfer charges in your budget.

What the product records and what gaps mean

Activity counts measure keyboard/mouse use, not the text typed. If detailed activity detection is unavailable, the agent may show approximate activity or idle information. URL/app capture depends on settings and OS/browser accessibility; empty URLs do not prove no browser use. Active time is not proof of work quality. Screenshots, URLs and window titles can contain sensitive material.

By default, screenshots are taken about once a minute while active and connected; the idle threshold is five minutes. Images are compressed and resized to reduce storage. Screenshot capture needs an active session and skips idle periods. Screenshots, captured web addresses and window titles are protected with encryption. Some records, such as account details and activity counts, require the protection of your server and backup controls. Keep infrastructure backups encrypted as well.

The monitoring gate pauses collection outside monitoring hours or while the backend is unreachable. Some already collected activity can wait locally for upload, but this is limited and is not continuous offline recording. Failed screenshot uploads are skipped and not replayed. Sleep, permission failures and storage/network outages can cause gaps. License expiry does not itself block ingestion, but it does not guarantee no data loss either.

Monitoring data stays in your deployment by default; optional S3-compatible storage sends encrypted objects to your configured provider. Portal signup, email, billing and setup-code delivery use external PTM/provider services. The first local administrator is authorised with a short one-time code only after a provider-confirmed card trial or purchase. The server redeems it over HTTPS, binds the returned signed licence to its own server ID, verifies the signature and recipient email, then performs licence checks locally. Its periodic licence check-in sends only the licence key, the server ID and a random per-run ID used to spot copied servers. Website assistant messages may use an external answer provider: never paste employee data, logs containing secrets or setup codes there.

Where to change settings

Changes to server settings need the deployment administrator. Avoid editing generated files or changing encryption secrets; use the setup and recovery instructions supplied with your release.

Trial & licensing

Pick a trial or a paid plan from pricing - a trial needs a verified card, so there is no trial without one. Once the payment provider confirms it, the setup code arrives by email; enter it on your dashboard (see Activate and create the first admin). See your plan, employee limit and renewal date any time under Settings → Licence & plan.

Account, email and billing help

Your customer-portal account (for billing) is separate from your dashboard admin account (for daily use) - resetting one does not touch the other. On the portal sign-in page use Forgot password?. If it says your email is not verified yet, use the Resend verification email button in that message (or create the account again with the same email to be sent a fresh link; this never changes your password). Check spam, and use the newest email link (they expire after 30 minutes).

Coming back from checkout doesn't mean payment went through yet - refresh the portal once your provider confirms it. On a trial, watch the trial end date and cancel beforehand if you don't want to be charged. Manage or cancel billing from the subscription section. If checkout won't load, contact support rather than trying to pay again.

If the setup code email doesn't arrive, check spam, then use Email me a new setup code in the portal. It's safe to repeat.

• Renewals, upgrades and trial-to-paid reach your server by themselves: it checks in with PTM at start-up and every five minutes, sending its licence key, Install ID, a random process ID and a fresh clock-verification challenge (never monitoring data). Use Check for updates under Settings → Licence & plan to pick a change up straight away. The server needs outbound HTTPS to cleanwork.ptmsoftware.live to activate and check in; if it cannot connect, a trial requires a signed refresh within two hours; other connected customer-installed licences allow up to seven days. Access always ends at the trial or paid-period deadline if earlier. A purchased permanent offline licence file has no recurring check. Missing it locks employee data access until a successful refresh.
• An expired trial or licence blocks the dashboard's data views and adding employees or devices - it doesn't delete anything or stop already-enrolled agents from recording. Renew and everything comes back.
• Employee limits come from your plan: Team 5, Starter 15, Business 75, Enterprise unlimited; a trial allows up to 15. At the limit, block or remove someone who's left to free a seat for a new hire. If you move to a smaller plan, the most recently added employees are locked until you free seats.
• One plan, its own servers. Each plan covers a set number of servers. The server that redeems the code is registered to your account automatically; to move a connected licence to a replacement server, release the old server in the customer portal and request a new setup code. Self-service releases are limited to three per rolling 30 days. Permanent offline replacements require PTM support. A copied server (for example a restored backup started next to the original) counts as a second server: PTM notices both running, and the newer copy stops receiving renewals until one is shut down.
• Permanent offline activation is available for purchased perpetual licences only. Download the isolated server's activation request, upload it in the verified purchaser's portal with the newest setup code, then import the signed licence file on the server. Keep both files and your database/uploads backups. Offline seat changes need a new signed file, and the server slot cannot be released through the portal.
• Your licence is verified locally on every request, against a PTM signature built into the product. It's never sent to or shown in the browser.

Data & retention

• Encrypted at rest. Screenshots, captured URLs and window titles are encrypted using 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

More information about data protection is on the security page.

Backup, restore and retention operations

Screenshot retention defaults to 90 days. Cleanup is periodic, not an exact-time deletion guarantee. Storage outages or backlog can delay removal. Use the current supported release and ask your operator to check deletion success and disk growth.

Screenshot cleanup does not expire activity, sessions, accounts, bucket versions or backups. Audit records have a separate retention policy, default 365 days. Ask your operator to apply and verify any audit-retention change on an existing deployment. Define the remaining lifecycles separately with your operator. Keep old storage profiles/credentials available while retained objects still reference them. Do not delete metadata and stored objects independently without a reviewed procedure.

Back up both ptm-clearwork-mongo-data and ptm-clearwork-uploads, the installer's .env, image versions, proxy configuration and external screenshot objects if configured. The uploads backup includes encryption secrets and must be treated as confidential.

1. Agree on backup frequency, retention, maximum acceptable data loss and restoration time. Keep encrypted copies off the host with restricted access.
2. For a simple consistent offline backup, schedule downtime, run the installer stop command and verify both containers stopped. Monitoring pauses during this period.
3. Use your infrastructure backup tool to snapshot/archive both volumes as one recovery set, plus configuration and external storage. Do not copy live MongoDB files as an ordinary file backup; online backups need a MongoDB-aware operator procedure.
4. Restart and verify health, login, agent reconnect and fresh uploads. Verify the backup completed and is readable.
5. Restore periodically to an isolated host using recorded image versions. Restore both volumes and settings before starting. Confirm the original Install ID, old screenshot decryption, activity and a test agent. Keep restored production credentials isolated from the real fleet until a planned cutover.

If a previously configured dashboard asks for a first admin again, check Docker context, volume identity and database logs before creating replacements. Containers can be recreated against surviving volumes. A lost database without backups cannot be reconstructed; agents must register again. Preserve surviving encryption secrets while deciding recovery.

Updates and employee communication

Back up, record the current image versions and read release notes first. Download the installer for the intended release before running update: an old script retains its old default image tag and does not discover newer releases automatically. Test on an isolated restored copy. Database changes may require restoring the matching recovery set for rollback, rather than simply running an old image.

After updating, verify health, admin login, original Install ID, old screenshot decryption and fresh agent activity. Desktop installers are distributed separately; pilot each OS before wider installation. Uninstall is not an upgrade/recovery procedure. Quitting/removing an agent does not erase its server history; block or remove as appropriate. Remove startup entries/local data only after deciding whether pending activity must sync.

Before rollout, tell employees the monitoring hours, fields collected, retention, people allowed to view data and internal support contact. Explain tray status, required permissions and why data can have gaps. Limit admin access and establish a process for correcting misunderstood activity records. Your organisation determines these policies.

For support, provide release, OS/architecture, failure time/timezone, deployment topology, affected-device count and redacted errors. Do not send raw volumes, employee screenshots, encryption keys, setup codes or credentials. Use PTM support.

Production acceptance and capacity checks

Pilot 5–10 representative devices, then expand in stages. Include every OS/architecture/browser, shift-start bursts, simultaneous dashboard reviewers, historical report queries, screenshot retrieval, server restart, sleep/wake and brief network failure. Health returning 200 is not a capacity test.

Have your administrator monitor CPU, memory, free disk, response times, data growth, failed requests, new screenshots and employee status. Suggested pilot targets: p95 ordinary API latency below one second, p95 uploads below five seconds, no sustained 5xx/429 errors, no missing expected screenshots while active and connected, no growing cleanup backlog, sustained CPU below 70%, and 30% free memory/disk headroom. These are validation targets, not an SLA. Use docker stats and host/proxy monitoring. Increase resources or reduce capture frequency when targets fail, then repeat with realistic data and review traffic.

For every desktop package, record the exact release and check registration, credential persistence, native input/idle, foreground app, browser URL, screenshot readability, login auto-start, reconnect, schedule boundaries/overnight hours, revocation, upgrade and uninstall. A successful installation alone does not confirm that device permissions allow capture. Re-test after OS/browser or endpoint-policy changes.

Troubleshooting

Start here: identify whether one employee device or the whole team is affected. Check the monitoring schedule, server reachability and available disk space before reinstalling anything. After each change, test one device and confirm a fresh screenshot, activity entry and correct status.

Collect the right information for support

Include the product release, OS/browser version, device CPU type, affected-device count, time and timezone, steps already tried and the exact redacted error. State whether the problem affects old data, new data or both.

Server logs: run ./ptm-clearwork logs on Linux/macOS or .\install.ps1 logs on Windows from the installer's folder. Employee log locations:

• Windows: %APPDATA%\PTM Clearwork\agent_debug.log
• macOS: ~/Library/Application Support/PTM Clearwork/agent_debug.log
• Linux: ~/.config/PTM Clearwork/agent_debug.log (the desktop configuration location may differ).

Remove employee screenshots, captured URLs, passwords, tokens, setup codes and activation keys before sharing logs. Contact hello@ptmsoftware.live for product support or sales@ptmsoftware.live for billing.

Choose what to remove

Removal is separate from setup. Taking the server off a machine and taking the agent off an employee computer are two different jobs, and neither does the other's work. Pick the one you need:

Remove the server

This takes the whole Cleanwork by PTM server off the machine it runs on. It does not touch any employee's desktop agent; see Remove the agent from a computer for that. Run it on the server itself. Each option is one command, with nothing else to type.

Both options start the same way. The command:

1. stops and removes the mongo and server containers and the ptm-clearwork Docker network;
2. removes the Docker images it downloaded (ptmtech/ptm-clearwork-server and ptmtech/ptm-mongo, every tag, about 1.6 GB) and the unnamed Docker volume the database container leaves behind.

They differ only in what happens to your data. Option 1 asks first and, by default, keeps it. Option 2 deletes it without asking.

Option 1: Remove the software, keep my data

The safer choice, and the right one if you might come back. Run the command below with no extra option. After the two steps above, it asks one question:

Also DELETE all data (database + screenshots + secrets)? This cannot be undone [y/N]

Answer N (or just press Enter) and the two data volumes and the .ptm-clearwork folder are kept. Running the install command again later, even much later, downloads the images again and restores exactly where you left off: same employees, history, admin accounts and Install ID. Answer Y and it continues exactly like Option 2.

Linux & macOS - open a terminal and run:

curl -fsSL https://cleanwork.ptmsoftware.live/install.sh -o ptm-clearwork && chmod +x ptm-clearwork && ./ptm-clearwork uninstall

Windows - open PowerShell and run:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force; irm https://cleanwork.ptmsoftware.live/install.ps1 -OutFile install.ps1; if ($?) { .\install.ps1 uninstall }

Option 2: Remove everything, including all data

One command, no questions. Use it only when you are sure.

Linux & macOS - open a terminal and run:

curl -fsSL https://cleanwork.ptmsoftware.live/install.sh -o ptm-clearwork && chmod +x ptm-clearwork && ./ptm-clearwork uninstall --purge && rm -f ptm-clearwork

Windows - open PowerShell and run:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force; irm https://cleanwork.ptmsoftware.live/install.ps1 -OutFile install.ps1; if ($?) { .\install.ps1 uninstall -Purge }; Remove-Item .\install.ps1 -ErrorAction SilentlyContinue

After the two steps above, it also:

3. permanently deletes the two data volumes, ptm-clearwork-mongo-data and ptm-clearwork-uploads - every employee record, activity log, screenshot and the encryption key that protects them;
4. deletes the local .ptm-clearwork folder (its generated compose file and .env, which holds your licence key), and finally the installer file itself.

Safety checks

Before it deletes anything, the command confirms its install folder is one it created itself. If the folder resolves to your whole home directory, or is missing the installer's own marker, it stops with Refusing to remove an unsafe or unowned install directory (nothing was deleted) and leaves everything - containers, volumes, images - exactly as it was. An image that another container on the same machine still uses is reported and skipped rather than forced off.

Remove the agent from a computer

Removing the app from an employee computer does not free that employee's seat or erase their history on the server. To free the seat, block the employee in the dashboard (see Employees and account details); their history is kept. Remove deletes it.

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"