OpenReplay
Before you install
Section titled “Before you install”These answers used to sit on this app’s store listing. They moved here on 2026-08-17: a shopper deciding whether to install is not reading six hundred words of Q&A, and the listing page is the pitch. The knowledge is no less true for being off the storefront: it is the part you want before you commit, which is what a guide is for.
Is this the enterprise edition?
Section titled “Is this the enterprise edition?”No. Community images with an empty licence key. Upstream’s enterprise directory is separately licensed and is not part of this package, so nothing here depends on buying anything later.
Do my visitors’ sessions leave my estate?
Section titled “Do my visitors’ sessions leave my estate?”No. The recorder posts to your ingest endpoint, the replay is written to your bucket, and the dashboard that plays it back is behind your gate. The only thing a visitor’s browser fetches from you is the recorder script itself.
What does it need to run?
Section titled “What does it need to run?”PostgreSQL, ClickHouse and S3-compatible object storage. All three attach as integrations. PostgreSQL and ClickHouse can be another stack on this estate or an external service, decided per deployment rather than baked in. Object storage is always external: SHC ships no S3 server of its own, so make the buckets at a hosted provider (Backblaze B2, Hetzner Object Storage, Cloudflare R2 or any S3-compatible service) and bind the s3 plug to an s3 connection or an external-s3 front. The install is refused without it or vars.s3.endpoint. See Object storage for apps.
Projects for your own clients
Section titled “Projects for your own clients”A web app that records sessions here needs a project key, and the projects var mints them so nobody has to click through the dashboard first. It’s a list of names, each matching [A-Za-z0-9][A-Za-z0-9_-]*:
vars: projects: - portal-web - docs-siteOn every install and update the grant-replay-projects hook creates a live project for any name that lacks one. It writes the row OpenReplay’s own create writes and matches names ignoring case the way the dashboard does, so Portal-Web made by hand counts as portal-web and a rerun creates nothing new. A name held only by a deleted project gets a new one. The hook logs granted <name> and never prints a key. A name outside the charset fails the hook before it touches the database. Dropping a name deletes nothing and renames nothing.
A recording’s metadata can only be filtered on once its key is registered on the project, and OpenReplay drops a key it doesn’t know. projectMetadata registers them on every project named in projects:
vars: projects: - portal-web projectMetadata: - appThe same hook takes each key into the first of a project’s ten free slots, the way the dashboard does. A key already there in any case stays where it is, and a project with no free slot fails the hook by name. Dropping a key from the list removes nothing.
To read the keys back, run the on-demand job:
shc job run list-replay-projects -s <stack> --waitIt prints one name=project_key line per declared name that has a live project. It creates nothing: a name the hook hasn’t reached yet goes to stderr as missing <name>. On incus and apple a job’s stdout and stderr arrive as one stream, so keep only the lines matching ^[A-Za-z0-9][A-Za-z0-9_-]*=[0-9A-Za-z]{20}$. No missing line or error can take that shape.
A project key is a public ingest identifier, safe to ship inside a client. Point the tracker at this deployment’s ingest endpoint:
new Tracker({ projectKey: "<project_key>", ingestPoint: "https://<host>/ingest" });