Skip to content
DocsGitHub

local

Sentry for local development

Start the Local control-plane daemon

Options:

Option Description
--foreground Run in the foreground
--host <host> Loopback host (default: "localhost")
--port <port> Control-plane port (default: "8969")

Show Local control-plane status

Stop the Local control-plane daemon

Restart the Local control-plane daemon

List retained envelopes for a Local session

Arguments:

Argument Description
<session...> Session ID or unique name

sentry local envelope view <session envelope...>

Section titled “sentry local envelope view <session envelope...>”

View a raw Local envelope

Arguments:

Argument Description
<session envelope...> Session and envelope ID

List decoded events for a Local session

Arguments:

Argument Description
<session...> Session ID or unique name

sentry local event view <session event...>

Section titled “sentry local event view <session event...>”

View a decoded Local event

Arguments:

Argument Description
<session event...> Session and event ID, or its first 8+ characters

Start the local dev server and tail events

Options:

Option Description
-p, --port <port> Port to listen on (default: "8969")
-H, --host <host> Hostname to bind to (default: "localhost")
-q, --quiet Suppress per-envelope tail output
-f, --filter <filter>... Only show items of this type (repeatable: error, transaction, log, ai)
-F, --format <format> Output format: human (default) or json (NDJSON on stdout) (default: "human")
-a, --attributes Also show SDK attributes, under each transaction, span and log or in JSON
--open Open Sentry Local UI in the browser
--max-envelopes <max-envelopes> Maximum envelopes retained by this receiver or session
--session <session> Create a daemon-owned telemetry session with this label

Examples:

Terminal window
# Start the server and tail events
sentry local
# Use a custom port
sentry local --port 9000
# Receive into a daemon session that outlives this terminal
sentry local serve --session worker
# Only show errors and logs (filter out transactions)
sentry local -f error -f log
# Only show AI/agent spans
sentry local -f ai
# Suppress per-envelope tail output
sentry local --quiet
# Stream NDJSON for scripts and agents
sentry local --format json
# Start the server and open the Sentry Local UI
sentry local --open

Create a Local telemetry session

Arguments:

Argument Description
<name...> Optional session label

Options:

Option Description
--clientId <clientId> Idempotency key for retried agent session creation
--host <host> Loopback host (default: "localhost")
--port <port> Control-plane port (default: "8969")
--max-envelopes <max-envelopes> Maximum envelopes retained by this receiver or session (default: "500")

sentry local session retention <session...>

Section titled “sentry local session retention <session...>”

View or change session envelope retention

Arguments:

Argument Description
<session...> Session ID or unique name

Options:

Option Description
--max-envelopes <max-envelopes> Maximum envelopes retained by this receiver or session

List Local telemetry sessions

View a Local telemetry session

Arguments:

Argument Description
<session...> Session ID or unique name

Close a Local telemetry session

Arguments:

Argument Description
<session...> Session ID or unique name

Clear a Local telemetry session

Arguments:

Argument Description
<session...> Session ID or unique name

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)
--host <host> Hostname for the local server (default: "localhost")
-f, --filter <filter>... Only show items of this type (repeatable: error, transaction, log, ai)
-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")
-F, --format <format> Output format: human (default) or json (NDJSON on stdout) (default: "human")
-a, --attributes Also show SDK attributes, under each transaction, span and log or in JSON
--open Open Sentry Local UI in the browser
--max-envelopes <max-envelopes> Maximum envelopes retained by this receiver or session
--session <session> Create a daemon-owned telemetry session with this label

Examples:

Terminal window
# Run a Node.js dev server with the local server enabled
sentry local run -- npm run dev
# Run a Django dev server with the local server enabled
sentry local run -- python manage.py runserver
# Capture into a daemon session, inspect it after the app exits, then clean up
sentry local run --session web -- npm run dev
sentry local session list --json
sentry local session view web --json
sentry local session retention web --max-envelopes 2000
sentry local event list web --json
sentry local event view web <event-id> --json
sentry local envelope list web --json
sentry local envelope view web <envelope-id> --json
sentry local session reset web
sentry local session close web
sentry local daemon status
sentry local daemon stop
# Run your app and open the Sentry Local UI
sentry local run --open -- npm run dev
# Stream agent-relevant NDJSON without SDK housekeeping envelopes
sentry local run --format json -f error -f transaction -f log -f ai -- npm run dev

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.

Most apps don't need a DSN either. If your app has no DSN configured, events flow only to the local server — nothing reaches your Sentry organization and no production quota is used. If a DSN is set, the SDK sends to both Sentry and the local server. A few features need a DSN to work; see SDK setup.

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

Runs a command with SENTRY_SPOTLIGHT set to the local server's URL. Node.js and Python SDKs read it and send envelopes to the local server with no code changes. Other runtimes need a line of setup; see SDK setup.

If nothing is listening on the port, a server is started in the background and shut down when your command exits. If something already is — the Spotlight desktop app's own sidecar, or a sentry local serve in another terminal — the command attaches to it as an SSE consumer, so events still tail to your terminal either way.

The Local daemon behind --session is the exception: it only takes session traffic. When it holds port 8969, a plain local run captures on a free port and says so. Add --session <name> to capture into the daemon instead. With an explicit --port that the daemon holds, the command stops with an error.

With no command, local run picks one from the project, in this order:

  1. package.json scripts: dev, develop, serve, then start
  2. manage.py: python manage.py runserver (Django)
  3. app.py, then main.py: a top-level app = FastAPI(...) runs with python -m uvicorn <module>:app --reload, and a top-level app = Flask(...) with python -m flask --app <module>:app run, using the variable the app is assigned to. A top-level app or application built by create_app() or make_app() uses the framework that factory builds when it is defined in the same file, or else the one that pyproject.toml or requirements.txt declares. With no top-level app, a top-level def create_app(): or def make_app(): factory runs with python -m uvicorn <module>:create_app --factory --reload for FastAPI or python -m flask --app <module>:create_app run for Flask. Docstrings, strings, and comments are ignored. A file with an if __name__ == "__main__": block, or with no app, runs as python <file>, with a hint when it imports FastAPI or Flask
  4. wsgi.py: a Flask app runs with python -m flask --app wsgi:app run, and a file with an if __name__ == "__main__": block as python wsgi.py
  5. FLASK_APP set, in a directory with app.py, main.py, wsgi.py, pyproject.toml, or requirements.txt: python -m flask run
  6. go.mod: go run .
  7. docker-compose.yml or compose.yml: docker compose up

Python commands use the project's virtualenv even when it is not activated: VIRTUAL_ENV, then .venv/, then venv/. Without one, they use python, or python3 when only that is on your PATH. The flask --app option needs Flask 2.2 or later; with an older Flask, pass the command after --. Pass a command after -- to skip detection.

Env vars injected into the child process:

Variable Value
SENTRY_SPOTLIGHT http://localhost:<port>/stream
<PREFIX>SENTRY_SPOTLIGHT http://localhost:<port>/stream
SENTRY_TRACES_SAMPLE_RATE 1 (unless already set)
SENTRY_RELEASE sentry-cli-local (unless already set)

The <PREFIX> variants put the URL where your bundler can inline it into browser code: PUBLIC_ (SvelteKit, Astro, Qwik), NEXT_PUBLIC_ (Next.js), VITE_ (Vite), NUXT_PUBLIC_ (Nuxt), REACT_APP_ (Create React App), VUE_APP_ (Vue CLI), and GATSBY_ (Gatsby). The browser SDK does not read them on its own yet.

When local run sees wrangler dev and a wrangler.json, wrangler.jsonc, or wrangler.toml, it also adds --var SENTRY_SPOTLIGHT:<url>, because Wrangler does not pass process env vars to Worker code. An explicit --var SENTRY_SPOTLIGHT:... is kept. No project file is changed.

sentry local run --verify -- <command> starts your app, waits for its first event, then stops it. It exits 0 once an event arrives. It fails if the app exits, crashes, or sends nothing within the timeout (30 seconds, or --timeout <seconds>). When port 8969 is busy, it verifies on a free port.

A Cloudflare Worker sends nothing until it handles a request, so send one to it while --verify waits.

Node.js and Python servers. Nothing to do. They read SENTRY_SPOTLIGHT.

Browser apps (Next.js, Vite, and other bundlers). Pass the prefixed variable to the Spotlight integration in your client config:

instrumentation-client.ts
const spotlight = process.env.NEXT_PUBLIC_SENTRY_SPOTLIGHT;
// Vite: const spotlight = import.meta.env.VITE_SENTRY_SPOTLIGHT;
Sentry.init({
dsn: "...",
integrations: spotlight
? [Sentry.spotlightBrowserIntegration({ sidecarUrl: spotlight })]
: [],
});

Cloudflare Workers. @sentry/cloudflare ignores the SENTRY_SPOTLIGHT binding in the build that Wrangler bundles. Send through tunnel instead, with a DSN set. A placeholder DSN works, because the tunnel sends everything to the local server:

export default Sentry.withSentry(
(env: Env) => ({
dsn: env.SENTRY_DSN ?? (env.SENTRY_SPOTLIGHT ? "https://local@localhost/0" : undefined),
tunnel: env.SENTRY_SPOTLIGHT,
// Local capture still works through tunnel. This only stops a second
// copy of each event when a bundler picks the SDK's dev build.
spotlight: false,
}),
app,
);

While local run is active, tunnel sends Worker events only to the local server, even with a real DSN.

Features that need a DSN. Without one, the browser SDK drops session replays and does not add trace headers to its requests, so browser and server traces do not link. The Python SDK drops logs still buffered when the process exits. To get these, set a placeholder DSN such as https://local@localhost/0 while you run under local run. In the browser, send through tunnel instead of the integration, so nothing goes to the placeholder and nothing arrives twice:

Sentry.init({
dsn: spotlight ? "https://local@localhost/0" : "...",
tunnel: spotlight,
});

If your backend runs on a different origin than the page, even just another port, also add it to tracePropagationTargets. By default the browser SDK adds trace headers only to same-origin requests, so without it browser and server traces still do not link. The backend's CORS settings must allow the sentry-trace and baggage headers:

Sentry.init({
dsn: spotlight ? "https://local@localhost/0" : "...",
tunnel: spotlight,
// Your API server, when it is not on the page's origin
tracePropagationTargets: ["http://localhost:8000"],
});

Not supported yet. The Next.js edge runtime (@sentry/vercel-edge) has no Spotlight support. Edge errors still arrive through the Node.js server, but edge messages and logs do not.

Use --open with sentry local or sentry local run to launch the Sentry Local UI (local.sentry.dev) in your browser. The UI connects to the local receiver via the loopback stream endpoint and provides a visual workspace for browsing errors, traces, logs, and AI spans captured during the session.

The --open flag requires a loopback --host (localhost, 127.0.0.1, or ::1). The hosted UI reads the SSE stream without changing retained receiver data. A loopback-served viewer can clear a receiver and reset or close a scoped daemon session. Session data stays in memory for the duration of the server; nothing is sent to sentry.io unless a DSN is configured.

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)

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] [SERVER] [http.server] GET /spans [200] [52ms] [4 spans] [trace:4c79f60c]
14:32:03 [INFO] [SERVER] User logged in [user_id=1234] [region=us]
14:32:04 [WARNING] [BROWSER] Cart is empty [page.tsx:24:19] [onClick]

Errors show their level, the exception type, message, and the newest stack frame from your app. Messages, such as captureMessage calls and Python logging records, show their level and text, plus the logger name when there is one. Transactions show the operation, duration, and span count. Logs show the severity level, message, and custom attributes. Attributes the SDK adds itself are hidden: sentry., http., url., db., server., code., thread., logger., and similar prefixes, the scope user (user.id, user.email, user.name, user.username, user.ip_address), Python's asctime, request and server_time, Rust's os.name, os.version and parent_span_id, and Ruby's parameters. Your own attributes, such as user.plan, still show. Add --attributes (-a) to list the hidden ones under each log line.

Events and logs use the same labels: a warning is [WARNING] whether the SDK sent warning or warn, and an event's logger shows as [logger:name]. A log's logger name is an SDK attribute, so it shows only with -a.

The source tag comes from the event's platform and runtime, so a Next.js or SvelteKit app shows [BROWSER] for client events and [SERVER] for server events. Logs and spans don't carry that, so they're tagged [BROWSER] when they show signs of the browser SDK (a pageload, navigation, ui.* or resource.* span, a browser instrumentation origin, browser.* attributes, or a session replay ID) and from the SDK name otherwise. A browser log sent while no replay is recording has none of these, so it is tagged from the SDK name.

A session replay prints one line when it starts, with its short ID and first page, such as [REPLAY] [BROWSER] replay 4d1c5b0e http://localhost:3000/. The segments it sends every few seconds after that don't print anything.

Use --filter / -f to narrow the output to specific event types. The flag is repeatable, so -f error -f log shows only errors and logs. The error filter covers every event item, so it includes messages too.

SDKs that stream spans (JavaScript SDK 11 and later) send each span on its own. The tail groups them back into one line per segment, such as a request or a pageload, with the segment's duration and the number of other spans sent with it. Spans whose segment wasn't in the same batch, like web vitals sent after a pageload or children sent before their segment, print as one line named after the segment, such as Pageload [+3 spans]. A single such span prints in full with [+1 span], so the counts still add up. Add --attributes (-a) to list every span with its attributes under the segment line; --format json always gives one record per span.

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

sentry local shows rich output for AI agent spans when your SDK instruments with OpenTelemetry semantic attributes:

14:32:01 [TRACE] [SERVER] [gen_ai] chat anthropic/claude-4-sonnet [1200ms] [5 spans]
14:32:02 [TRACE] [SERVER] [mcp] tools/call search_files [320ms]
14:32:03 [TRACE] [SERVER] [db] SELECT users [postgresql] [12ms]
14:32:04 [ERROR] [SERVER] RateLimitError: API quota exceeded [api_client.py:42]

GenAI operations show the model name, MCP tool calls show the tool being invoked, and database queries show the system and query summary. This works automatically when your Sentry SDK is configured with AI/LLM integrations.

To watch only agent activity, filter to the ai item type with -f ai, and add -f error to keep errors alongside agent spans.

Use --format json (or -F json) for machine-readable NDJSON output, one JSON object per envelope item.

local run supports the same JSON, attribute, and filter options while it starts your app and injects the receiver URL. For an agent-friendly stream without SDK housekeeping envelopes, filter to error, transaction, log, and ai items. Each JSON line looks like this:

{"type":"transaction","timestamp":1700000001,"op":"gen_ai","label":"chat anthropic/claude-4-sonnet","duration_ms":1200,"span_count":5,"source":"server"}
{"type":"error","timestamp":1700000002,"level":"error","error_type":"RateLimitError","message":"API quota exceeded","source":"server"}
{"type":"log","timestamp":1700000003,"level":"info","message":"User logged in","attributes":{"user_id":1234},"source":"server"}
{"type":"message","timestamp":1700000004,"level":"warning","message":"Cart is empty","logger":"shop.cart","source":"server"}

This is useful for AI coding agents and automation tools that need to consume Sentry events programmatically.

Events with an exception type are "type":"error" records. Events without one, such as captureMessage calls and Python logging records, are "type":"message". -f error returns both, so a script that keeps errors with jq 'select(.type=="error")' should also keep "message" if it wants them.

In JSON mode, event records are versioned NDJSON on standard output. Startup, connection, and shutdown messages stay on standard error, so an agent can pipe the evidence stream without parsing terminal status text. Records include schema_version, trace_id, and, when supplied by the SDK, event_id and envelope_id for exact correlation. timestamp is always epoch seconds, even when the SDK sends ISO 8601 strings. Strings never contain ANSI color codes, so colored log output from tools like werkzeug or uvicorn comes through as plain text. Log records list only custom attributes, like the tail; add -a to also get the attributes the SDK adds (except sentry.*). level is the value the SDK sent, so logs use warn and events use warning. In local run --format json, the wrapped app's standard output is also forwarded to standard error, leaving standard output exclusively for NDJSON observations.

The repository includes a small Hono server that produces a normal database request, an agent/MCP trace, and an intentional failure. It sends only to the local server unless you explicitly set SENTRY_DSN.

In one terminal, start the local receiver:

Terminal window
sentry local serve --format json --attributes

In another, run the fixture with Spotlight pointed at that receiver:

Terminal window
SENTRY_SPOTLIGHT=http://localhost:8969/stream \
pnpm --filter sentry run ts test/fixtures/local-agent-server.ts

Then exercise each telemetry shape:

Terminal window
curl http://127.0.0.1:3030/api/users/42
curl -X POST http://127.0.0.1:3030/api/agent/run \
-H 'content-type: application/json' \
-d '{"prompt":"Where is the rate limit configured?"}'
curl -i http://127.0.0.1:3030/api/broken

The final request intentionally returns HTTP 500. The fixture is for local experimentation only; do not run it with production credentials.

Use --session <name> to capture into the shared loopback daemon and retain data after your foreground command exits. Sessions keep up to 500 envelopes by default (--max-envelopes accepts 1 to 50,000) for three hours after closing and subsequent ingestion. Session commands start the daemon when it isn't running; sentry local daemon start starts it ahead of time. The daemon exits on its own 30 seconds after it has no sessions, open or closed, so one started with sentry local daemon start and given no session stops shortly after; the next session command starts it again. Stopping or restarting the daemon (sentry local daemon restart) clears all sessions. A running sentry local run --session then warns that its session stopped capturing. Your app keeps running, so restart the command to capture again.

The sentry local run examples above walk through a full session lifecycle: capture, inspect sessions, events, and envelopes, then reset, close, and stop the daemon. sentry local serve --session worker captures into a session the same way without wrapping a command.

sentry local session create <name> --json returns separate SDK ingest and viewer read capability URLs. Keep these URLs private. --clientId <key> makes retried session creation idempotent. Use the session ID when multiple sessions share a label.

sentry local session list, sentry local event list, and sentry local envelope list print tables; add --json for the full records. The event table shows each event ID cut to the shortest unique prefix of at least 8 characters, and sentry local event view accepts that prefix. A prefix that matches more than one event fails and lists the matching IDs.