Screenshots, time intervals, and storage retention in Cattr

Last reviewed against the current server-application code on October 16, 2026.

This guide explains how screenshot capture is controlled, how screenshots are associated with time intervals, what happens when intervals are deleted, and how Cattr automatically reclaims screenshot storage.

Screenshot policy levels

Cattr can control screenshot capture at several levels:

1. instance/environment;
2. company;
3. project;
4. user.

The available screenshot states are:

• Forbidden — screenshots must not be captured;
• Required — screenshots must be captured;
• Optional — lower-level settings may decide;
• Any — internal/default state used when no instance-wide override is applied.

Instance-wide override

The server supports:

SCREENSHOTS_STATE=ANY

ANY is the default.

Setting the environment value to:

SCREENSHOTS_STATE=REQUIRED

forces screenshots on globally.

Setting it to:

SCREENSHOTS_STATE=FORBIDDEN

forces screenshots off globally.

A forced instance-level REQUIRED or FORBIDDEN state overrides the company, project, and user settings.

Company screenshot policy

Administrators can configure the company screenshot policy in the company settings.

The company-level choices are:

• Forbidden
• Required
• Optional

If the company policy is Required or Forbidden, project and user screenshot controls are locked to that policy.

If the company policy is Optional, projects and users may define more specific behavior.

Project screenshot policy

Each project has its own screenshot state.

When the company policy is Optional, a project can be configured as:

• Required
• Forbidden
• Optional

The project policy has priority over the individual user setting.

In practical terms:

• project Required → screenshots are stored regardless of the user's screenshot preference;
• project Forbidden → screenshots are not stored;
• project Optional → the user's screenshot setting decides whether screenshots are stored.

User screenshot policy

When the company and project policies allow it, a user's screenshot setting determines whether screenshots are captured for projects configured as Optional.

The user-level setting effectively allows screenshots to be either required or forbidden for that user.

For example:

Company: Optional
Project: Optional
User: Required

→ screenshots are stored.

Company: Optional
Project: Optional
User: Forbidden

→ screenshots are not stored.

But:

Company: Optional
Project: Required
User: Forbidden

→ screenshots are still stored because the project requires them.

Screenshot interval

Each user has a screenshots_interval setting.

The server currently accepts values from 1 to 15 minutes.

This value controls the interval used by the client when screenshot capture is enabled for that user/project combination.

How screenshots are stored

A screenshot belongs to a time interval.

When an interval containing a screenshot is accepted by the server, Cattr checks the effective project/user screenshot policy before saving the image.

Screenshots are stored as JPEG files.

Cattr also creates a thumbnail for each screenshot.

Inside the configured Cattr storage disk, screenshot files are kept under:

screenshots/

and thumbnails under:

screenshots/thumbs/

The current screenshot service stores JPEG images at quality 50 and generates thumbnails with a width of 280 pixels.

Deleting a time interval

Time intervals use soft deletion in the database.

Deleting an interval sets its deletion state rather than immediately removing the database row.

However, the screenshot files associated with that interval are deleted when the interval is deleted.

Both the full screenshot and its thumbnail are removed.

This means:

Deleting a time interval also deletes its screenshot files.

Current permission rules allow an administrator to remove intervals generally, while normal users and other roles may remove intervals that belong to themselves according to the applicable access policy.

Bulk interval removal is also supported for users with the corresponding permission.

Because screenshot removal is tied to interval deletion, deleting intervals should not be used merely as a storage-cleanup mechanism.

Screenshot thinning

Cattr has a separate screenshot storage cleanup mechanism called thinning.

Thinning removes screenshot files while leaving the corresponding time intervals in the database.

After thinning:

• tracked time remains;
• activity values remain;
• the interval remains available in reports;
• the screenshot file and thumbnail are gone.

This is fundamentally different from deleting the interval itself.

When thinning starts

Cattr calculates screenshot-storage usage against a configured storage size.

The relevant environment variables are:

SCREENSHOTS_STORAGE_SIZE_BYTES=
CLEANER_THRESHOLD_USED_SPACE_PERCENTAGE=75
CLEANER_WATERLINE_PERCENTAGE=15

SCREENSHOTS_STORAGE_SIZE_BYTES defaults to the total size of the filesystem containing the configured screenshot storage.

The default thinning threshold is 75% used.

If usage is below the threshold, the screenshot rotation command does nothing.

With the default settings, once thinning begins, Cattr continues removing eligible screenshots until usage falls below the calculated waterline.

The target is calculated as:

total storage
× threshold
× (1 - waterline)

With the defaults:

100% × 75% × 85% = 63.75%

So thinning begins at 75% usage and attempts to reduce eligible screenshot storage until total usage is approximately 63.75% or lower.

Automatic thinning

Administrators can enable Auto thinning in the company settings.

When enabled, Cattr schedules the screenshot rotation command weekly.

The command is:

php artisan cattr:screenshots:rotate

The scheduled command still checks the configured storage threshold. Enabling auto thinning does not mean screenshots are deleted every week regardless of storage usage.

Manual thinning

The About page contains storage information including:

• used space;
• total space;
• free space;
• last thinning time;
• number of screenshots currently eligible for thinning.

The storage section also provides a thinning action.

Starting cleanup from the UI queues the same screenshot rotation process.

If storage usage has not reached the configured threshold, the rotation command will not remove screenshots.

The command can also be run manually:

php artisan cattr:screenshots:rotate

Which screenshots can be removed by thinning

The storage cleaner does not treat every screenshot as removable.

A screenshot is eligible for thinning only when all of the following are true:

• its task is not marked as important;
• its project is not marked as important;
• the owning user does not have permanent_screenshots enabled;
• the screenshot file still exists.

Eligible screenshots are processed starting from the oldest interval IDs.

This allows important projects/tasks to protect their screenshots from normal storage thinning.

Protecting screenshots from thinning

If screenshots for a project or task must be retained, mark the relevant project/task as important.

The cleaner explicitly excludes screenshots associated with important tasks or important projects.

There is also a legacy/internal per-user permanent_screenshots flag which the cleaner respects, although it is not currently exposed as a normal editable field in the user settings UI.

Do not rely on filesystem permissions or manually moving screenshot files as a retention strategy.

Monitoring storage

The storage information endpoint is:

GET /api/about/storage

It reports:

• free space;
• used space;
• configured total storage;
• thinning threshold;
• whether thinning is currently needed;
• number of screenshots eligible for thinning;
• whether thinning is currently running;
• timestamp of the last thinning operation.

This information is also displayed in the web interface.

“Screenshots available for thinning” is zero

If Cattr reports that storage is heavily used but screenshots_available is zero, check whether the remaining screenshots are protected.

Common reasons include:

• the related tasks are marked important;
• the related projects are marked important;
• users have permanent screenshots enabled;
• screenshot files have already been removed while the intervals remain.

Thinning stops when there are no eligible screenshot files left, even if the configured target usage has not been reached.

Deleting screenshots vs deleting intervals

Use the appropriate operation for the intended result:

Goal	Operation	Time interval remains	Screenshot remains
Stop collecting future screenshots	Change screenshot policy	Yes	Existing screenshots unchanged
Free screenshot storage	Thinning	Yes	No, for selected eligible screenshots
Remove tracked interval	Delete interval	Soft-deleted	No
Preserve screenshots during automatic cleanup	Mark task/project important	Yes	Yes

Storage sizing recommendations

Screenshot storage can grow quickly on installations with many active users.

When planning storage:

• place persistent Cattr storage on a volume sized for screenshot growth;
• monitor /api/about/storage or the corresponding UI;
• enable automatic thinning if indefinite screenshot retention is not required;
• mark only genuinely important projects/tasks as important;
• back up screenshots separately if they must be retained for compliance or audit purposes.

The thinning mechanism is a capacity-management feature, not a backup system.

Before changing retention settings

Before enabling aggressive thinning or reducing available storage:

1. confirm which projects/tasks are marked important;
2. confirm whether screenshots must be retained for legal or business reasons;
3. back up the screenshot storage if historical images must not be lost;
4. verify the configured storage size and threshold;
5. run thinning and check the storage page afterwards.

Deleted screenshot files are not restored from the associated time interval.

Troubleshooting

If screenshots are not being captured:

1. check SCREENSHOTS_STATE;
2. check the company screenshot state;
3. check the project screenshot state;
4. check the user's screenshot state;
5. check the user's screenshot interval;
6. verify that the desktop client is actually uploading intervals/screenshots;
7. check server and desktop logs.

If screenshots disappear unexpectedly:

1. check whether the interval itself was deleted;
2. check whether auto thinning is enabled;
3. check the last thinning time;
4. check whether storage usage crossed the configured threshold;
5. inspect the storage-cleaner configuration;
6. verify that the screenshot storage volume is persistent.

When asking for help, include:

• Cattr Server version;
• deployment type;
• effective screenshot policies at company/project/user level;
• whether auto thinning is enabled;
• storage threshold configuration;
• output from the storage information page;
• relevant server logs.

Do not post private employee screenshots or unredacted activity data in a public Discussion.