What is the Sidecar?

The Spotlight Sidecar is a lightweight local proxy server that sits between your application and the Spotlight UI. It’s the backbone of Spotlight’s real-time debugging capabilities.

How It Works

Your Application → Sentry SDK → Sidecar Server → Spotlight UI
                                      ↓
                              [Stores & Streams]
                              Errors, Traces, Logs

The sidecar:

1. Receives telemetry data from your application via Sentry SDKs
2. Stores events in memory for quick access
3. Streams events to connected UIs via Server-Sent Events (SSE)
4. Provides APIs for querying historical data (used by MCP tools)

Key Features

Real-Time Event Streaming

Uses Server-Sent Events (SSE) to push events to the UI as they happen. No polling, no delays - see errors and traces the moment they occur.

In-Memory Storage

Events are buffered in memory, allowing you to:

• Browse historical events during your session
• Query past errors and traces
• Analyze patterns over time

Multiple Connection Modes

The sidecar supports different ways to run:

• Standalone: Run independently and connect any UI
• Embedded: Automatically started by framework integrations
• CLI-wrapped: Started by spotlight commands
• Desktop app: Bundled with the Spotlight desktop application

Built-in UI

The sidecar includes a web-based UI accessible at http://localhost:8969 (default port):

• No additional setup required
• View events directly in your browser
• Works alongside desktop app and MCP clients

Configuration

Default Settings

The sidecar comes pre-configured with sensible defaults:

• Port: 8969
• Event endpoint: http://localhost:8969/stream
• UI endpoint: http://localhost:8969

Custom Port

You can configure the port in several ways:

Via CLI:

spotlight -p 3000

Via SDK:

import sentry_sdk

sentry_sdk.init(
    spotlight="http://localhost:3000/stream",
)

Running the Sidecar

Choose the method that fits your workflow:

CLI Commands Run with spotlight command

NPX Quick start with npx

Webpack Plugin Auto-start with webpack

Docker Run in a container

Desktop App Built-in with desktop app

Quick Start Options

Standalone Server:

# Using CLI
spotlight server

# Using npx
npx @spotlightjs/spotlight

With Your Application:

# Run your app with Spotlight
spotlight run npm run dev

For MCP Integration:

# Start with MCP support
spotlight mcp

Architecture

Communication Flow

1. Your Application sends telemetry to the sidecar via HTTP POST
2. Sidecar validates, stores, and broadcasts events
3. UI Clients receive events via SSE connections
4. MCP Clients query events via stdio protocol

Multiple Clients

A single sidecar instance can serve multiple clients simultaneously:

• Browser-based UI - View in any web browser
• Desktop app - Dedicated application window
• MCP clients - AI assistants (Cursor, Claude, etc.)
• Multiple apps - Different services sending to the same sidecar

All clients receive the same events in real-time.

Data Persistence

Events are stored in memory only by design:

Benefits:

• ✅ Fast access and streaming
• ✅ No disk I/O overhead
• ✅ Automatic cleanup on restart

Trade-off:

• ⚠️ Events are lost when sidecar stops

This is intentional - Spotlight is for active development, not long-term storage.

SDK Integration

Your application sends events to the sidecar via Sentry SDKs.

Quick Setup

Most SDKs support automatic detection via environment variable:

export SENTRY_SPOTLIGHT=1
# or specify custom URL
export SENTRY_SPOTLIGHT=http://localhost:8969/stream

Or configure explicitly:

Node.js

import * as Sentry from '@sentry/node';

Sentry.init({
  spotlight: process.env.NODE_ENV === 'development',
  // or explicitly:
  // spotlight: "http://localhost:8969/stream"
});

Python

import sentry_sdk

sentry_sdk.init(
    spotlight=True,  # Uses SENTRY_SPOTLIGHT env var
    # or explicitly:
    # spotlight="http://localhost:8969/stream"
)

Browser

import * as Sentry from '@sentry/browser';

Sentry.init({
  integrations: [Sentry.browserTracingIntegration()],
});

Use Cases

Local Development

Run the sidecar alongside your development server to see errors and traces as you code.

Integration Testing

Start the sidecar during tests to capture and analyze test failures with full context.

Mobile Development

Point your mobile app to your machine’s sidecar to debug on real devices:

spotlight: "http://192.168.1.100:8969/stream"

Microservices

Run one sidecar and point all your services to it for unified debugging across your stack.

When to Use Each Method

Use CLI When:

• You want simple command-line control
• You need to wrap your application
• You want to stream events to terminal

Learn more about CLI →

Use NPX When:

• You want the quickest setup
• You don’t need the CLI features
• You just want the sidecar running

Learn more about NPX →

Use Webpack Plugin When:

• You’re using webpack
• You want automatic sidecar lifecycle management
• You want sidecar to start/stop with your build

Learn more about Webpack →

Use Docker When:

• You’re containerizing your dev environment
• You need isolation from your host system
• You’re deploying to a remote dev server

Learn more about Docker →

Use Desktop App When:

• You want a GUI experience
• You prefer desktop applications
• You’re developing mobile or headless apps

Learn more about Desktop App →

Security

Local-Only by Design

The sidecar is designed exclusively for local development. It only accepts connections from:

• localhost: Always allowed (RFC 6761 reserved name)
• This machine’s IPs: Any hostname that resolves to an IP assigned to this machine, including:
  • Loopback addresses (127.0.0.1, ::1)
  • Local network IPs (e.g., 192.168.x.x, 10.x.x.x)
  • VPN IPs (e.g., Tailscale, Zerotier)
• spotlightjs.com: The official Spotlight website (HTTPS only)

Custom Local Hostnames

You can use custom hostnames in your /etc/hosts file (e.g., myapp.local pointing to 127.0.0.1). These are trusted without TTL validation because they’re under your local control. The sidecar determines that a hostname is from /etc/hosts when DNS lookup fails but the OS resolver finds it.

VPN and Remote Access

The sidecar supports access via VPN services like Tailscale or Zerotier. If your hostname resolves to a VPN IP assigned to your machine, it will be allowed. This is useful for:

• Accessing Spotlight from other devices on your VPN
• Using custom domains that point to your VPN IP
• Debugging mobile apps via VPN connection

DNS Rebinding Protection

The sidecar implements protection against DNS rebinding attacks, which could potentially allow a malicious website to access your local sidecar.

How DNS rebinding works:

1. An attacker controls evil.com with a short DNS TTL
2. User visits evil.com, which initially resolves to the attacker’s server
3. The attacker’s page loads malicious JavaScript
4. The attacker rebinds evil.com to 127.0.0.1 (or another machine IP)
5. JavaScript makes requests to evil.com (now pointing to the machine)

Our mitigation:

• DNS records with TTL less than 1 hour are rejected as potentially unsafe
• This means an attacker would need to set a TTL >= 1 hour to have their hostname resolve to localhost
• With such a high TTL, rebinding to localhost would make the attacker’s site inaccessible for at least 1 hour

This makes DNS rebinding attacks impractical against Spotlight. Hostnames defined only in /etc/hosts (not in public DNS) are automatically trusted since they’re under local control and DNS rebinding cannot affect them.

Additional protection for non-loopback IPs: For machine IPs other than loopback (e.g., 192.168.x.x), the risk is even lower because:

• External access requires explicit port forwarding or firewall configuration
• Most machines are behind NAT, which blocks inbound connections by default
• VPN IPs are only accessible from within the VPN network

Development Only

Spotlight should never be enabled in production environments:

• Use environment checks to restrict to development only
• The sidecar has no authentication - anyone who can reach it can read your telemetry
• Events are stored in memory and cleared on restart

Next Steps

• Learn about CLI commands - Control sidecar via terminal
• MCP Integration - Connect to AI assistants