Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.usenightowl.com/llms.txt

Use this file to discover all available pages before exploring further.

​
1. Sign up and create your app

Create your NightOwl account at usenightowl.com/signup, add your application, and connect your PostgreSQL database. After the app is created, the dashboard reveals an agent token and the connected-app ID — copy both, you’ll paste them into your .env in step 3.

​
2. Install the agent

Add the NightOwl agent to your Laravel app (it pulls in laravel/nightwatch automatically as a dependency): 
composer require nightowl/agent

​
3. Configure environment variables

Add these to your .env file: 
NIGHTOWL_TOKEN=your-agent-token
NIGHTOWL_APP_ID=your-app-id
NIGHTOWL_DB_HOST=your-pg-host
NIGHTOWL_DB_PORT=5432
NIGHTOWL_DB_DATABASE=nightowl
NIGHTOWL_DB_USERNAME=nightowl
NIGHTOWL_DB_PASSWORD=your-password
NIGHTOWL_TOKEN is the token you copy from the NightOwl dashboard. The agent uses it to authenticate inbound payloads from laravel/nightwatch and to authenticate itself when reporting health to the platform.NIGHTOWL_APP_ID is the connected-app ID, shown alongside the token after you create the app. The agent embeds it in alert payloads so the View issue link in emails and webhooks points directly at the issue page. Without it, links fall back to the generic dashboard root.If you’re running NightOwl alongside Nightwatch’s hosted agent, you’ll also set NIGHTWATCH_TOKEN — that’s your real Nightwatch token, used by the Nightwatch SDK to reach Laravel Cloud’s hosted ingest in parallel.

​
4. Run the agent

php artisan nightowl:agent
The agent starts on port 2407 by default. Nightwatch will automatically send telemetry to it.

​
5. Open the dashboard

Go to usenightowl.com and select your app. You should see data flowing in within seconds.
The agent creates all required database tables automatically on first run. No manual migrations needed.

​
Next steps

Agent configuration

Every environment variable, artisan command, and tuning knob — one reference page.

Production deployment

Supervisor, systemd, and Docker recipes for running the agent under a process manager.

Filtering and context

Nightwatch::ignore(), Context::add(), and upstream sampling/redaction — trim and enrich the dataset.

Health monitoring

Read ingest rate, drain rate, and buffer depth — and know when to scale.

Alert channels

Wire Slack, Discord, email, or webhooks for new-issue notifications.

MCP server

Let Claude Code, Codex, or Cursor browse and update issues from your editor.