Skip to main content

​
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.
Your PostgreSQL must be reachable from NightOwl over a public IP — managed providers like Supabase, Neon, or RDS qualify; a localhost or private-network database is rejected with “Host must be publicly routable.” NightOwl creates the nightowl_* tables but does not create the database itself, so point it at a database that already exists. On Supabase that’s postgres, on Neon it’s neondb — or create a dedicated one first (CREATE DATABASE nightowl;).
Firewall or IP allowlist on your database? The dashboard reads your telemetry by connecting to your PostgreSQL from a single static IP:
178.156.227.16
Add 178.156.227.16/32 to your database’s allowlist (RDS security group, Supabase network restrictions, Cloud SQL authorized networks, your firewall’s inbound rules). This is one address, not a range — a /32 covers it. If NightOwl can’t reach your database, connecting the app fails with a connection-timeout error.

​
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_DB_SSLMODE=prefer
Use the direct or session connection (port 5432), not a transaction-mode pooler (Supabase’s port 6543). The agent runs as a long-lived process that holds its database connection and sets a session-level option (synchronous_commit) for drain throughput. A transaction-mode pooler (Supabase Supavisor on 6543, PgBouncer in transaction mode) hands each transaction a different backend and doesn’t keep session state, so it’s the wrong fit for the agent’s persistent drain connection — use the session pooler or direct connection instead. Managed Postgres also requires SSL, so set NIGHTOWL_DB_SSLMODE=require.
  • Supabase — use the Session pooler (port 5432, IPv4-reachable) or the Direct connection from Database → Connect; database postgres.
  • Neon — the standard endpoint host on port 5432 (avoid the -pooler host variant for the agent); database neondb.
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. Install NightOwl

php artisan nightowl:install
This publishes config/nightowl.php and runs the migrations that create the nightowl_* tables in the PostgreSQL database you configured in step 3. It also runs a fork-safety probe to confirm the agent’s SQLite + pcntl_fork buffer will work on your host.
The nightowl_* tables live in the BYO PostgreSQL database you configured above — not your app’s primary database. Migration history is tracked there too, so nightowl:install (and php artisan nightowl:migrate) are idempotent: safe to run on every environment and every deploy, even when several environments share one NightOwl database. See Sharing one database across environments.

​
5. Route your logs to NightOwl

Requests, queries, jobs, cache, and exceptions flow automatically once the agent is running. Logs are the exception: Laravel only writes to the channels in your active log stack, and the nightwatch channel is not added to that stack for you. Add nightwatch to your LOG_STACK so log records reach the agent: 
LOG_STACK=single,nightwatch
If your app overrides the stack channel in config/logging.php directly, add nightwatch to its channels array instead: 
// config/logging.php
'stack' => [
    'driver' => 'stack',
    'channels' => ['single', 'nightwatch'],
    'ignore_exceptions' => false,
],
The nightwatch log channel is registered automatically by laravel/nightwatch, but it is only consulted when it is part of the stack your app logs to. Until you add it, Logs will stay empty in the dashboard even though every other event type appears normally. Make sure LOG_CHANNEL=stack (Laravel’s default) so the stack — and therefore nightwatch — is actually used.

​
6. Run the agent

php artisan nightowl:agent
The agent starts on port 2407 by default. Nightwatch will automatically send telemetry to it.
Port 2407 is also Nightwatch’s default ingest port. If you’re already running the Nightwatch agent (nightwatch:agent), the two will collide and the NightOwl agent won’t start. To run both side by side, set NIGHTOWL_AGENT_PORT to a free port and enable parallel mode — see Running Alongside Nightwatch.

​
7. Open the dashboard

Go to usenightowl.com and select your app. Generate some traffic first — hit a route, dispatch a job, or trigger an exception — then refresh; records appear within seconds. A freshly installed agent on an idle app shows an empty dashboard until traffic flows. To confirm the agent itself is up, curl its health endpoint on the host where it runs: 
curl http://127.0.0.1:2409/status

​
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.