Dashboard

HappyView ships with a web dashboard that provides a visual interface for most of what the admin API offers. The instance serves it itself, and it authenticates via atproto OAuth. The sidebar shows only the pages your permissions allow.

On a fresh instance the dashboard opens a setup wizard, which covers the service identity and ends with the telemetry question. With no operators in the database and no SUPERADMIN_DID set, the first person to log in is made an operator with the superadmin privilege and every permission, so log in first with the handle you want to run the instance.

Data

Lexicons

Navigate to Lexicons to see every lexicon the instance holds. Each entry shows the NSID, type (record, query, procedure), source, and more. Once the instance has somewhere to publish lexicons, the table adds its publishing columns.

Adding a lexicon

Click Add Lexicon and choose Local or Network.

Local lexicons are defined by you. The editor shows two side-by-side panels (tabs on a narrow screen):

• Lexicon JSON: define your lexicon
• Lua Script: write the script for a query or procedure

The Lua Script panel only appears when the lexicon’s defs.main.type is query or procedure. For record lexicons, only the JSON panel is shown. A project is how to write these in another language.

HappyView generates a default script when you first set the type to query or procedure. The template updates when the type changes, but once you edit the script your changes are preserved.

For a record lexicon, Index records from the network decides whether the instance ingests its collection, and Enable backfill for lexicon indexes its existing records as well.

Network lexicons are fetched from the atproto network. Enter an NSID (e.g. xyz.statusphere.status) and HappyView resolves it automatically. If found, the lexicon JSON is displayed in a read-only editor. Click Add to track it. See Lexicons: Network lexicons for how resolution works.

JSON editor

The JSON editor provides real-time validation against the atproto Lexicon v1 schema:

• Validation for Lexicon format
• Auto-complete for definition types (record, query, procedure, subscription), property types (string, integer, boolean, ref, union, blob, cid-link, etc.), and schema structure (defs, main, properties, required)
• Enforces the required top-level shape: lexicon, id, and defs.main

Lua editor

The Lua editor offers completion, hover and signature help from the declarations the interpreter provides, so it covers the libraries installed on the instance.

See Scripts for how a script is written.

Records

Navigate to Records to browse all indexed atproto records. Records are grouped by collection and searchable. Each record shows its AT URI, author DID, and the raw record JSON.

Spaces

Navigate to Spaces to view the instance’s spaces. The page needs spaces:read, and reading a space’s records is written to the event log.

Backfills

Navigate to Backfills to view and manage backfills. Click New backfill to start one for any record lexicon’s collection. The table shows each backfill’s collection, accounts, status and start time. Click a row to open Backfill details, with its Source (such as Crawl, Replay or Network store), its progress, and how its Record scripts ran. Progress updates in real time. A running backfill can be cancelled or paused from there: it shows “cancelling” while the worker finishes its current batch, then “cancelled”. See Backfill for how the process works.

Pending happyview#319

These labels match happyview#319, which is open. Until it merges, the page reads Backfill and its button Create Backfill Job.

Jobs

Navigate to Jobs to view background jobs, with their status, input, progress and result. The page needs jobs:read.

Dead Letters

Navigate to Dead Letters to view record and label events whose script failed every attempt. Each entry shows the URI, the action, the error, the number of attempts and the record. You can Retry, Re-index or Dismiss selected entries or everything matching the filter. The sidebar badge shows the count of unresolved dead letters. See Dead letters.

Access

Users

Navigate to Users to manage who can access the admin API and dashboard. You can add operators by DID, assign permissions individually or via a template (Viewer, Maintainer, Manager or Full Access), and remove them. The operator with superadmin is marked Owner and has every permission; Transfer Ownership moves it to another operator. See Permissions for what each permission grants.

Linked Repos

Grant the instance OAuth access to a repo, and mint the invite that lets its account holder approve it. See Linked repos.

API Keys

Create and revoke admin API keys for automation. Each key is scoped to specific permissions and tied to the operator who created it. See API Keys for details.

API Clients

Register and manage third-party API clients. Each client gets an hvc_… client key and hvs_… client secret. You can configure the client type (confidential or public), allowed origins, scopes, and per-client rate limits. See Authentication: API client identification for how clients are used.

Integrations

Scripts

Navigate to Scripts to list, create and edit the instance’s scripts. A row is marked when no installed interpreter can run it. A script that still reads v2 globals offers Migrate; see Migrating scripts to v3. A script’s own page shows a summary of its performance.

Script performance

Navigate to Script Performance to see how often each script runs, how long it takes, and how much of that time is the script’s own. The page needs metrics:read, which every template holds.

The 1h, 24h, 7d and 30d buttons pick the window. The first two are kept in memory, so they cover this instance’s runs alone and read back the last day after a restart. The other two are read from the database and summed over every instance sharing it. Stored metrics are kept for as long as event logs (event_log_retention_days, 30 days by default), and the page says so when that is shorter than the window.

• Scripts lists each script with its Kind and Source (Project file or Dashboard), Runs, p50, p95, Max, Errors, Timeouts, Memory peak, and Code · host: the mean time in the script’s own code, then waiting on the host calls it made. It holds up to 1,024 scripts, and the page counts any more that weren’t recorded.
• Clicking a script opens its detail: the same figures, Instructions per run, graphs over the window, and Where a run’s time goes.
• Record pipeline lists what each record costs on its way in, by collection: Records, Rate, p50, p95, Script vs platform, Stage means, Failed, Timeouts and Dead-lettered.

Setting script_metrics_enabled to false stops recording new runs, and the page shows a warning. What was recorded stays until it leaves its window.

Plugins

Manage installed plugins and configure plugin secrets. Plugin secrets are encrypted at rest and need TOKEN_ENCRYPTION_KEY. See Plugins for details.

Labelers

Configure labeler subscriptions for content labeling. See Labelers for details.

System

General

Configure instance-level settings:

• Instance Identity: the instance’s name, URI, logo, terms of service and privacy policy, shown on OAuth authorization screens.
• Data Retention: how long a finished backfill’s details are kept.
• Backfill Performance: the concurrency of a backfill.
• Scripts: Instruction limit and Request wall clock (seconds).
• Event Logs: their retention, verbose logging and, with events:purge, Purge Event Logs.

Most can also be set through the environment, and a dashboard value takes precedence. Each field shows where its value came from. The Configuration reference lists the keys.

Database

Shows storage use and the instance’s write-ahead log checkpoints. On SQLite, Reclaim disk space schedules a one-time VACUUM; see Database setup for when you need one.

Telemetry

Choose whether the instance sends reports and what they contain, and read the exact report first. See Telemetry.

Service Identity

Configure the atproto service identity for your HappyView instance: a did:web derived from your public URL, a did:plc you control, or an attached atproto account. This determines the DID that signs service-level interactions on the network. See Service identity.

Lexicon Publishing

Set the rules that publish your lexicons to the network. See Publishing lexicons.

OAuth Keys

List, rotate and revoke the keys the instance signs OAuth requests with. See OAuth keys.

XRPC Proxy

Control which unrecognized XRPC methods are forwarded, and where. Choose from four modes: Disabled (block all proxy requests), Open (proxy everything, the default), Allowlist (only proxy NSIDs matching your patterns), or Blocklist (proxy everything except matching patterns). Allowlist and blocklist modes accept NSID patterns with trailing wildcards (e.g. com.example.*). Locally registered lexicons are always served regardless of this setting. See Hardening for how to choose, and XRPC Proxy for the API.

ENV Variables

Manage script variables, which every script receives as ctx.env at run time. They hold shared configuration without hardcoding it in a script. Despite the page’s name, these aren’t the instance’s environment variables. See Script variables.

Event Logs

View the event log. Events include operator changes, lexicon uploads, permission changes, backfill starts, and more. Each entry shows the event type, severity, actor, subject, and timestamp.

Experiments

Toggle experimental feature flags for your instance, such as feature.spaces_enabled. See Feature flags.

About

The About page shows the current HappyView version and instance configuration: public URL, database backend, Jetstream URL, relay URL, and PLC directory URL. It also shows the Jetstream connection’s protocol, host, compression and lag.

Next steps

• Lexicons: how lexicons drive HappyView’s indexing and routing
• Scripts: write custom query and procedure logic
• Permissions: manage operator access to admin features
• Configuration reference: every environment variable