> ## 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.
# Quick Start
> Get NightOwl running in 5 minutes.
## 1. Sign up and create your app
Create your NightOwl account at [usenightowl.com/signup](https://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):
```bash theme={null}
composer require nightowl/agent
```
## 3. Configure environment variables
Add these to your `.env` file:
```env theme={null}
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](/agent/running-alongside-nightwatch), 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
```bash theme={null}
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](/agent/configuration#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:
```env theme={null}
LOG_STACK=single,nightwatch
```
If your app overrides the `stack` channel in `config/logging.php` directly, add `nightwatch` to its `channels` array instead:
```php theme={null}
// 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
```bash theme={null}
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](/agent/running-alongside-nightwatch).
## 7. Open the dashboard
Go to [usenightowl.com](https://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:
```bash theme={null}
curl http://127.0.0.1:2409/status
```
## Next steps
Every environment variable, artisan command, and tuning knob — one reference page.
Supervisor, systemd, and Docker recipes for running the agent under a process manager.
`Nightwatch::ignore()`, `Context::add()`, and upstream sampling/redaction — trim and enrich the dataset.
Read ingest rate, drain rate, and buffer depth — and know when to scale.
Wire Slack, Discord, email, or webhooks for new-issue notifications.
Let Claude Code, Codex, or Cursor browse and update issues from your editor.