Documentation
Telltale
Getting started
Updated
You install Telltale from the Scalpels catalog like any other product. The general flow is in Install a product. This page covers what is specific to Telltale.
Before you start
- Connect GitHub and Laravel Cloud to your Scalpels team (Connect GitHub, Connect Laravel Cloud).
- Telltale is Experimental, so your team needs supporter or partner access to install it.
- Telltale is for NativePHP apps. The client captures NativePHP Mobile and NativePHP Desktop signals; screen capture on mobile needs NativePHP Mobile 4.1 or later.
What the install provisions
Scalpels forks artisan-build/telltale into your GitHub account and creates the following in your Laravel Cloud account:
| Resource | Why Telltale needs it |
|---|---|
| Web compute on PHP 8.5 | Serves the dashboard, the device endpoints (/api/register, /api/ingest) and the MCP server (/mcp). |
| A Neon serverless PostgreSQL 18 database | Holds apps, installs, raw events, sessions, error groups and daily aggregates. The schema uses jsonb, so it cannot run on MySQL. |
| A managed queue | Delivers the Built for Cloud ownership webhook that Scalpels relies on. Ingest itself is synchronous. |
| The scheduler | Runs telltale:prune-events daily at 03:10, which enforces the raw-event retention window. |
No cache and no object storage are provisioned. Rate limiting and scheduler locks use the database cache store. After the first deploy, Scalpels runs php artisan migrate --force, which creates Telltale's tables and the Built for Cloud tables in the one database.
Telltale has no environment values to fill in at install time. It has no secret of its own: the values your devices use are minted inside Telltale after it is running. Every server setting has a working default; see Configuration.
Set a permanent domain first
Before you build any app against Telltale, settle on a stable address for the Telltale environment. Its laravel.cloud address works without extra setup, or you can use your own domain for an address you control. Do not change that address after client applications begin using it.
The domain matters because the Telltale URL is baked into each NativePHP build. A desktop or mobile build that has shipped cannot be pointed at a different URL, so a temporary Cloud hostname you later replace would strand every copy of that build.
Sign in
Open the deployment's URL. The landing page links to the dashboard; going there, or to /setup, asks you to sign in through Telltale's Built for Cloud sign-in. Once signed in you have three places:
- Apps (
/dashboard): create and manage the apps that report to Telltale. - Setup (
/setup): the same integration steps as this documentation, rendered by your deployment. - Account settings: your Built for Cloud account screens.
Create your first app
On Apps, enter a name for your NativePHP app and select Create app. Telltale shows a one-time ingest value beginning tti_. Copy it now: Telltale stores only a hash and cannot show it again. If you lose it, rotate it; see Managing apps.
Then install the client in your NativePHP app and give it that value; see Instrumenting your app.
Keeping it current
Your Telltale repository is your fork. Upgrade the server before you ship a client that uses a newer envelope version: a server refuses envelopes newer than it supports, with a message telling you to upgrade the server.