Configuration

Pulse is configured entirely through environment variables. Every one has a default, so an empty environment still runs.

How configuration loads#

Node 24 reads env files natively, so there is no dotenv dependency. Pulse loads .env.local first and then .env from the working directory. A variable already set in the real environment wins over both files, and .env.local wins over .env. Empty values are treated as unset.

Numeric variables must be positive integers. Anything else falls back to the default. Comma-separated variables are split on commas with whitespace trimmed.

Environment variables#

All variables read by `src/lib/env.ts`. The first group matches `.env.example`.
Variable	Default	Purpose
`DATABASE_URL`	empty	Postgres connection string. Empty uses the embedded PGlite archive. Example with the bundled compose file: `postgres://pulse:pulse@localhost:5544/pulse`.
`PORT`	`8787`	Port for the API and dashboard.
`PUBLIC_URL`	empty	Public base URL of the dashboard. When set, each Telegram issue starts with an "Open the dashboard" link to `PUBLIC_URL/#/reports/<day>`.
`REPORT_TIMEZONE`	`UTC`	IANA time zone that defines the newsletter's local day.
`REPORT_HOUR`	`13`	Local hour (0-23) at or after which the day's issue is generated, once per local day.
`TELEGRAM_BOT_TOKEN`	empty	Bot token from @BotFather. Sending needs both this and `TELEGRAM_CHAT_ID`.
`TELEGRAM_CHAT_ID`	empty	Target chat or channel, for example `@my_channel`. The bot must be an admin of the channel.
`ANTHROPIC_API_KEY`	empty	Optional. Adds a short written overview at the top of each issue, constrained to that day's data. Without it the issue is data only.
`ANTHROPIC_MODEL`	`claude-sonnet-5-5`	Model used for the written overview.
`SNAPSHOT_EVERY_MIN`	`5`	Minutes between collection cycles.
`STREAMS`	`on`	Set to `off` to disable the Solana firehose. The collector, API and dashboard keep running.
`SOLANA_RPC_URLS`	`https://api.mainnet-beta.solana.com`	Comma-separated Solana HTTP RPC endpoints.
`SOLANA_WS_URLS`	`wss://api.mainnet-beta.solana.com`	Comma-separated Solana WebSocket endpoints for the firehose log subscription. The public endpoint drops connections often. A dedicated endpoint keeps the stream steady.
`ROBINHOOD_RPC_URLS`	`https://rpc.mainnet.chain.robinhood.com`	Comma-separated Robinhood Chain RPC endpoints used to read launchpad factory logs.
`PGLITE_DIR`	`./data/pglite`	Directory of the embedded PGlite archive. Only used when `DATABASE_URL` is empty. Not listed in `.env.example`.

MCP server variable#

Variable	Default	Purpose
`PULSE_URL`	`http://localhost:8787`	Base URL of the Pulse API that `pulse-mcp` reads. Set it in the MCP client's `env` block. See MCP server.

Command-line flags#

Flags are read by the entry point src/main.ts (also reachable through pulse start and pulse collect).

Flag	Effect
`--once`	Run one collection cycle and exit. No firehose, no server.
`--jobs`	With `--once`, also import wallet labels and score wallets now instead of waiting for their cadence.
`--no-stream`	Do not start the Solana firehose, regardless of `STREAMS`.
`--no-server`	Do not start the API and dashboard.
`--migrate`	Apply migrations and exit.

Cadences that are not configurable#

Wallet label import: when the last import is older than 24 hours.
Wallet scoring: when the last run is older than 1 hour.
Newsletter: once per local day, at or after REPORT_HOUR.

Each of these is checked at the end of every collection cycle, so the effective resolution is SNAPSHOT_EVERY_MIN.

Secrets. Keep TELEGRAM_BOT_TOKEN, ANTHROPIC_API_KEY and any RPC URLs that embed an API key in your secret manager or an untracked .env. .env and .env.local are in the repository's .gitignore.