local

Sentry for local development

Commands

sentry local serve

Start the local dev server and tail events

Options:

Option	Description
-p, --port <port>	Port to listen on (default 8969) (default: "8969")
-H, --host <host>	Hostname to bind to (default localhost) (default: "localhost")
-q, --quiet	Suppress per-envelope tail output
-f, --filter <filter>...	Only show items of this type (repeatable: error, transaction, log)

sentry local run <command...>

Run a command with the local dev server enabled

Arguments:

Argument	Description
<command...>	Command to run

Options:

Option	Description
-p, --port <port>	Port for the local server (default 8969) (default: "8969")
--host <host>	Hostname for the local server (default localhost) (default: "localhost")
-V, --verify	Verify SDK sends events, then exit
-t, --timeout <timeout>	Kill the child after N seconds (0 = no timeout; defaults to 30 s in --verify mode) (default: "0")

All commands support --json for machine-readable output and --fields to select specific JSON fields.

sentry local runs a local development server that captures Sentry SDK envelopes from your dev stack and surfaces errors, traces, and logs in real time — right in your terminal. No authentication required.

If a server is already running on the port, the command attaches as an SSE consumer instead of starting a duplicate.

Examples

# Start the server and tail events (default)
sentry local

# Run your app with the local server auto-enabled
sentry local run -- npm run dev
sentry local run -- python manage.py runserver

# Use a custom port
sentry local --port 9000

# Only show errors and logs (filter out transactions)
sentry local -f error -f log

# Run quietly (suppress per-envelope tail output)
sentry local --quiet

sentry local run

Runs a command with SENTRY_SPOTLIGHT injected into the environment. The Sentry SDK automatically detects this variable and sends envelopes to the local server. No code changes needed.

Env vars injected into the child process:

Variable	Value
SENTRY_SPOTLIGHT	http://localhost:<port>/stream
NEXT_PUBLIC_SENTRY_SPOTLIGHT	http://localhost:<port>/stream
SENTRY_TRACES_SAMPLE_RATE	1

Endpoints

Method	Path	Description
POST	/stream	Envelope ingest
POST	/api/{projectId}/envelope/	Sentry SDK ingest path
GET	/stream	Server-Sent Events feed of incoming envelopes
GET	/health	Liveness check (returns OK)

Tail output

By default, incoming envelopes are pretty-printed to the terminal:

14:32:01 [ERROR]   [SERVER]  TypeError: x is not a function [app.ts:42:5] [handleRequest]
14:32:02 [TRACE]   [BROWSER] [http.client] GET /api/users [245ms] [3 spans]
14:32:03 [INFO]    [SERVER]  User logged in [user_id=1234] [region=us]

Errors show the exception type, message, and top stack frame. Transactions show the operation, duration, and span count. Logs show the severity level, message, and custom attributes.

Use --filter / -f to narrow the output to specific event types (repeatable):

sentry local -f error -f log    # only errors and logs

Use --quiet to suppress tail output entirely if you only need the SSE stream.