Configuration

Updated

Hone needs no configuration to run. Every setting below has a working default, and every resource connection, including the database and the queue, is injected by Laravel Cloud when Scalpels attaches the resource. Change a setting only when you want different behaviour.

Hone has no admin screen, so settings are environment variables. To change one, set it in the Hone environment's variables in Laravel Cloud and redeploy.

Values Scalpels and Laravel Cloud provide

You do not set any of these yourself:

Database, queue and application key. Laravel Cloud injects the connection settings for the resources Scalpels attached, and generates APP_KEY. Setting your own DB_*, QUEUE_CONNECTION or similar values would override the injected ones and break that resource.
HONE_URL, HONE_TOKEN and NIGHTWATCH_ENABLED in a connected app. Scalpels writes these when it attaches the app; see Connecting your apps.

Hone server settings

These are the settings the Scalpels manifest lists as optional:

Variable	Default	What it does
`HONE_RETENTION_RAW_HOURS`	`72`	How long individual raw events are kept. This is the main driver of disk use.
`HONE_RETENTION_AGGREGATE_DAYS`	`90`	How long daily aggregates are kept.
`HONE_RETENTION_SAMPLE_DAYS`	`7`	How long sample rows are kept.
`HONE_MCP_PATH`	`/mcp`	Where the MCP server is mounted. If you change it, update every agent that connects directly.
`HONE_QUEUE_CONNECTION`	unset	The queue connection ingest batches are dispatched on. Leave it unset: batches then go to the application's default connection, which on Laravel Cloud is the managed queue Scalpels attached.

Hone also reads these, for less common tuning:

Variable	Default	What it does
`HONE_RETENTION_TIMELINE_DAYS`	`400`	How long the per-minute activity buckets used by the activity and traffic tools are kept.
`HONE_ROLLUP_LATE_ARRIVAL_HOURS`	`24`	How far back each hourly rollup re-reads, so late events are still aggregated. The default is a guess; raise it if your apps' telemetry routinely arrives later than this. Older gaps are rebuilt with `hone:backfill`.
`HONE_ROUTE_PREFIX`	none	A URL prefix for `/ingest` and `/capabilities`. It does not move the MCP path. Leave it unset: Scalpels writes each attached app's `HONE_URL` as the base URL plus `/ingest`, so a prefix would stop those apps reporting.
`HONE_MAINTENANCE_OVERLAP_LOCK_MINUTES`	`120`	Releases the `hone:maintain` lock if a run dies without clearing it.
`HONE_HEALTH_INGEST_ACTIVE_MINUTES`	`60`	How recently an event must have arrived for the retention and freshness checks to judge; otherwise they report `idle`.
`HONE_HEALTH_MAINTENANCE_MAX_AGE_MINUTES`	`150`	Alarm if `hone:maintain` has not succeeded within this long.
`HONE_HEALTH_RETENTION_GRACE_HOURS`	`24`	Added to the raw retention window before the retention check alarms.
`HONE_HEALTH_AGGREGATE_MAX_AGE_HOURS`	`6`	Alarm if the newest daily aggregate is older than this.
`HONE_IPTOASN_PATH`	unset	Path to an uncompressed iptoasn.com TSV dataset on the server, used to label guest traffic by network in `guest_traffic_clusters`. The dataset is not shipped with Hone; without it, the network is left empty.

Leave the HONE_DB_* variables unset. Hone's telemetry shares the application's database by default. Setting any HONE_DB_* value moves telemetry to a separate PostgreSQL connection, and a Scalpels install has only the one database.

NIGHTWATCH_DEPLOY has no effect on the Hone server. It belongs in each connected app.

Connected app settings

These live in the environment of each app that reports to Hone. All are optional except the two Scalpels writes.

Variable	Default	What it does
`NIGHTWATCH_DEPLOY`	unset	The deploy id sent with every record, usually the short commit SHA. Set it on each deploy to make deploy comparison work.
`HONE_BUFFER`	`500`	Records held in memory before sending (console) or dropping the oldest (web requests).
`HONE_FLUSH_INTERVAL`	`60`	In console processes, the age in seconds at which the oldest record causes the buffer to be sent on the next write.
`HONE_TIMEOUT`	`0.5`	Request timeout in seconds for sends from web requests. Values below `0.05` are raised to `0.05`.
`HONE_CONNECT_TIMEOUT`	`0.5`	Connect timeout in seconds for sends from web requests. Values below `0.05` are raised to `0.05`.
`HONE_CONSOLE_TIMEOUT`	`5.0`	Request timeout for sends from console processes and queue workers. Falls back to `HONE_TIMEOUT` when that is set.
`HONE_CONSOLE_CONNECT_TIMEOUT`	`2.0`	Connect timeout for console sends. Falls back to `HONE_CONNECT_TIMEOUT` when that is set.
`HONE_APP`	`APP_NAME`	An identifier sent with every batch. Hone does not use it for naming; the app id comes from the credential.

The client is on only when both HONE_URL and HONE_TOKEN are set. There is no separate switch: remove either one to stop an app reporting. Sampling and redaction are configured in Nightwatch, not here.

Server commands

You can run these on the Hone environment with Laravel Cloud's command runner. None of them prints a secret.

Command	What it does
`php artisan hone:health`	Reports maintenance health. Add `--json` for machine-readable output.
`php artisan hone:maintain`	Runs the rollup and then the prune, as the scheduler does every hour.
`php artisan hone:rollup`	Rolls recent raw events into aggregates and activity buckets.
`php artisan hone:prune`	Deletes data past its retention window.
`php artisan hone:backfill <from> <to>`	Rebuilds aggregates and activity buckets for a UTC date range.

Apart from the one-time operator bootstrap, do not mint credentials through the command runner: Laravel Cloud keeps each command's output, which would retain the secret. Use the HTTP API described in Connecting your agent.