Skip to content
pols.so docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

Timeline

What a sandbox's timeline records, who sees it, how to turn on content capture, and how secrets are masked.

Every sandbox has a timeline: what happened in it, newest first. Open a sandbox on your account page to see it, or read it through the API or the MCP server.

What is recorded

Always recorded:

  • lifecycle calls and the statuses the sandbox reached
  • commands run through exec, with their command line, exit code and duration
  • desktop actions, and who took control of the desktop

Each event says who caused it.

With content capture on, the timeline also records the first and last 4 KiB of each command’s output, the text typed on the desktop, and screenshots with thumbnails. Content capture is off by default.

Never recorded: environment values, vault values and standard input. A command that received standard input has no output recorded either; its stdout reads [output not recorded: command received stdin].

Who sees it

Only your org sees a sandbox’s timeline. pols.so operators do not see it on their admin pages.

Turning on content capture

Content capture is set per sandbox and affects only events from then on:

  • on the sandbox’s page on the website, with the content capture switch
  • with the CLI: pols timeline SANDBOX --capture-content=true (and =false to turn it off again)
  • with the API: PUT /v1/sandboxes/{sandbox}/timeline (reference)
  • with the MCP tool sandbox_timeline_settings

Masking

Before an event is stored, its command line, output, typed text and errors are masked, best effort:

  • The values of the sandbox’s vault entries (at least 4 bytes, as the sandbox got them and as they are now) and of its environment variables (at least 8 bytes, the sandbox’s and the command’s own) become [redacted NAME].
  • Common token formats become [redacted]: Authorization, Bearer and Basic header values; sk-, ghp_, gho_, github_pat_, xoxb- and xoxp- tokens; AWS access key IDs; PEM private keys; and the values of token, secret, password and api_key pairs.

Other secrets in opted-in content can be recorded. The vault values a sandbox got are held in memory only, so after a restart of the server a vault value replaced since the sandbox was created is no longer masked. Leave content capture off for sandboxes that handle secrets pols.so does not know about.

How long it is kept

Events are kept for 30 days and screenshot thumbnails for 7 days. Each org’s timeline also has a size cap, beyond which its oldest events are deleted. Deleting a sandbox deletes its timeline. See Data retention.

Reading it

curl -H "Authorization: Bearer $POLS_API_KEY" "https://api.pols.so/v1/sandboxes/web/events?limit=50"

GET /v1/sandboxes/{sandbox}/events (reference) returns a page of events, newest first; page further with before set to next_before, and filter with type. A screenshot’s thumbnail is at GET /v1/sandboxes/{sandbox}/events/{event}/thumbnail. Over MCP, sandbox_events lists the events and sandbox_event_thumbnail returns a thumbnail.