Self-Hosted Sentry Configuration

Sentry CLI supports self-hosted Sentry instances. You’ll need to configure the base URL and, for OAuth authentication, a client ID.

Environment Variables

SENTRY_URL

Set SENTRY_URL to point to your self-hosted Sentry instance:

export SENTRY_URL=https://sentry.example.com

This variable affects:

API requests (all commands)
OAuth device flow (authentication)
Web UI URLs (opened in browser)

macOS/Linux
Windows (PowerShell)
Windows (CMD)
Docker/CI

.bashrc or .zshrc

# Add to your shell profile
export SENTRY_URL=https://sentry.example.com

Then reload your shell:

source ~/.bashrc  # or ~/.zshrc

# Set for current session
$env:SENTRY_URL = "https://sentry.example.com"

# Set permanently (user level)
[System.Environment]::SetEnvironmentVariable(
    'SENTRY_URL',
    'https://sentry.example.com',
    'User'
)

# Set for current session
set SENTRY_URL=https://sentry.example.com

# Set permanently
setx SENTRY_URL "https://sentry.example.com"

docker-compose.yml

services:
  app:
    environment:
      - SENTRY_URL=https://sentry.example.com
      - SENTRY_AUTH_TOKEN=${SENTRY_AUTH_TOKEN}

.github/workflows/deploy.yml

jobs:
  deploy:
    env:
      SENTRY_URL: https://sentry.example.com
      SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}

SENTRY_CLIENT_ID

OAuth device flow requires Sentry 26.1.0 or later. For older versions, use token-based authentication.

For OAuth authentication on self-hosted instances, you must create an OAuth application and set SENTRY_CLIENT_ID:

Create an OAuth Application

Log in to your self-hosted Sentry instance
Go to Settings > Developer Settings
Click Create New Application
Set application name (e.g., “Sentry CLI”)
Set Application Type to Public
Set Redirect URIs to http://localhost (required but unused for device flow)
Click Save
Copy the Client ID

Set the environment variable

export SENTRY_CLIENT_ID=your-client-id-here

Add this to your shell profile alongside SENTRY_URL.

Authenticate

sentry auth login

The CLI will use your self-hosted instance for the OAuth flow.

Example: Complete self-hosted setup

# Set base URL
export SENTRY_URL=https://sentry.example.com

# Set OAuth client ID (from Developer Settings)
export SENTRY_CLIENT_ID=abc123def456

# Authenticate
sentry auth login

# Use CLI normally
sentry issue list
sentry project list

Authentication Methods

OAuth Device Flow (Recommended)

Requirements:

Sentry 26.1.0 or later
Both SENTRY_URL and SENTRY_CLIENT_ID set
Public OAuth application created in Developer Settings

# Set variables
export SENTRY_URL=https://sentry.example.com
export SENTRY_CLIENT_ID=your-client-id

# Login
sentry auth login

Follow the prompts to complete authentication in your browser.

The OAuth flow uses SENTRY_URL for all authorization endpoints. Make sure your instance is accessible from your browser.

Token Authentication (Manual)

For older versions or if you prefer manual token management:

Create an auth token

Log in to your Sentry instance
Go to Settings > Account > API > Auth Tokens
Click Create New Token
Select scopes: project:read, project:write, org:read, event:read, event:write
Click Create Token
Copy the token (shown only once)

Set SENTRY_AUTH_TOKEN

export SENTRY_AUTH_TOKEN=your-token-here

Verify access

sentry auth status

You should see:

✓ Authenticated as [email protected]
Token source: SENTRY_AUTH_TOKEN

With SENTRY_AUTH_TOKEN set, the CLI uses this token directly and skips OAuth. This is useful for CI/CD and older Sentry versions.

Token Authentication (Alternative)

You can also use SENTRY_TOKEN instead of SENTRY_AUTH_TOKEN:

export SENTRY_TOKEN=your-token-here

Precedence: SENTRY_AUTH_TOKEN > SENTRY_TOKEN > stored OAuth token.

Verifying Configuration

Check auth status

sentry auth status

OAuth (Success)
Environment Token (Success)
Not Authenticated

$ sentry auth status
✓ Authenticated as [email protected]
Token source: oauth
Expires in: 55 minutes

$ sentry auth status
✓ Authenticated as [email protected]
Token source: SENTRY_AUTH_TOKEN

$ sentry auth status
Error: Not authenticated
Run 'sentry auth login' to authenticate.

Test API access

# List organizations
sentry org list

# List projects
sentry project list

# View a specific project
sentry project view my-project

If commands fail with connection errors, verify:

SENTRY_URL is correct and accessible
Your self-hosted instance is running
Firewall rules allow access

Check effective URL

The CLI uses SENTRY_URL for all operations. You can verify the active configuration:

# Check environment
echo $SENTRY_URL

# Test with verbose logging
SENTRY_LOG_LEVEL=debug sentry org list 2>&1 | grep -i "request to"

DSN Auto-Detection

When SENTRY_URL is set, the CLI only detects DSNs matching your self-hosted instance:

# With SENTRY_URL=https://sentry.example.com

# This DSN is detected:
# https://[email protected]/4505238

# This DSN is ignored (different host):
# https://[email protected]/4505238

This prevents mixing SaaS and self-hosted DSNs, which would cause API errors.

If you work with multiple Sentry instances, use separate shells or shell aliases with different SENTRY_URL values.

Configuration Directory

By default, the CLI stores authentication and cache data in ~/.sentry/. For self-hosted instances, you might want separate configuration directories:

# Use a separate config directory for self-hosted
export SENTRY_CONFIG_DIR=~/.sentry-selfhosted
export SENTRY_URL=https://sentry.example.com

sentry auth login

This keeps SaaS and self-hosted credentials separate.

Config Directory Contents

~/.sentry/
├── cli.db          # SQLite database
├── cli.db-wal      # Write-ahead log
└── cli.db-shm      # Shared memory file

The database stores:

OAuth tokens and expiry times
User information
Organization/project cache
Default org/project settings
Pagination cursors

Moving Between Instances

To switch between SaaS and self-hosted:

# SaaS alias
alias sentry-saas='SENTRY_CONFIG_DIR=~/.sentry sentry'

# Self-hosted alias
alias sentry-sh='SENTRY_CONFIG_DIR=~/.sentry-selfhosted SENTRY_URL=https://sentry.example.com sentry'

# Use them
sentry-saas org list
sentry-sh org list

Troubleshooting

Connection Refused

Error: Cannot connect to Sentry at https://sentry.example.com
Check your network connection and SENTRY_URL configuration

Solutions:

Verify the URL is correct: curl -I $SENTRY_URL
Check if Sentry is running
Verify firewall rules
Check DNS resolution: nslookup sentry.example.com

OAuth Client ID Required

Error: SENTRY_CLIENT_ID is required for authentication
Set SENTRY_CLIENT_ID environment variable or use a pre-built binary

Solutions:

Create an OAuth application in Developer Settings
Set SENTRY_CLIENT_ID environment variable
Or use token authentication instead

Sentry Version Too Old

Error: Failed to initiate device flow
404 Not Found

OAuth device flow requires Sentry 26.1.0+. For older versions:

Use manual token authentication:
```
export SENTRY_AUTH_TOKEN=your-token
```
Or upgrade your Sentry instance

SSL Certificate Errors

If your self-hosted instance uses self-signed certificates:

# NOT RECOMMENDED: Disable SSL verification (development only)
export NODE_TLS_REJECT_UNAUTHORIZED=0
sentry org list

Disabling SSL verification is insecure. Use proper certificates in production.

Better solutions:

Add your CA certificate to the system trust store
Use Let’s Encrypt for valid certificates
Use a proper SSL termination proxy

Wrong Instance Being Used

If commands hit the wrong Sentry instance:

# Check active configuration
echo $SENTRY_URL
echo $SENTRY_CLIENT_ID

# Check for conflicts in environment
env | grep SENTRY_

Make sure:

SENTRY_URL is set correctly
No conflicting values in .env files
Shell profile files don’t override your values

Best Practices

Use shell aliases for multiple instances

~/.bashrc

# SaaS
alias sentry-saas='unset SENTRY_URL && sentry'

# Self-hosted production
alias sentry-prod='SENTRY_URL=https://sentry.example.com SENTRY_CLIENT_ID=abc123 sentry'

# Self-hosted staging
alias sentry-staging='SENTRY_URL=https://sentry-staging.example.com SENTRY_CLIENT_ID=def456 sentry'

Use .env files per project

.env.production

SENTRY_URL=https://sentry.example.com
SENTRY_AUTH_TOKEN=your-token

Then load it:

source .env.production
sentry project list

Document OAuth setup for team

SENTRY_SETUP.md

# Sentry CLI Setup (Self-Hosted)

1. Install CLI: `npm install -g @sentry/cli-next`
2. Set environment variables:
   ```bash
   export SENTRY_URL=https://sentry.example.com
   export SENTRY_CLIENT_ID=<ask-team-lead>

Login: sentry auth login
Test: sentry org list

</Accordion>

<Accordion title="Use tokens in CI/CD, OAuth locally">
**Local development:**
```bash
export SENTRY_URL=https://sentry.example.com
export SENTRY_CLIENT_ID=abc123
sentry auth login

CI/CD:

env:
  SENTRY_URL: https://sentry.example.com
  SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}

This avoids OAuth flow complexity in CI while keeping local dev convenient.

Get Started

Core Concepts

Guides

Self-Hosted Sentry Configuration

Environment Variables

SENTRY_URL

SENTRY_CLIENT_ID

Authentication Methods

OAuth Device Flow (Recommended)

Token Authentication (Manual)

Token Authentication (Alternative)

Verifying Configuration

Check auth status

Test API access

Check effective URL

DSN Auto-Detection

Configuration Directory

Config Directory Contents

Moving Between Instances

Troubleshooting

Connection Refused

OAuth Client ID Required

Sentry Version Too Old

SSL Certificate Errors

Wrong Instance Being Used

Best Practices

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Environment Variables

​SENTRY_URL

​SENTRY_CLIENT_ID

​Authentication Methods

​OAuth Device Flow (Recommended)

​Token Authentication (Manual)

​Token Authentication (Alternative)

​Verifying Configuration

​Check auth status

​Test API access

​Check effective URL

​DSN Auto-Detection

​Configuration Directory

​Config Directory Contents

​Moving Between Instances

​Troubleshooting

​Connection Refused

​OAuth Client ID Required

​Sentry Version Too Old

​SSL Certificate Errors

​Wrong Instance Being Used

​Best Practices

Build docs developers (and LLMs) love

Environment Variables

SENTRY_URL

SENTRY_CLIENT_ID

Authentication Methods

OAuth Device Flow (Recommended)

Token Authentication (Manual)

Token Authentication (Alternative)

Verifying Configuration

Check auth status

Test API access

Check effective URL

DSN Auto-Detection

Configuration Directory

Config Directory Contents

Moving Between Instances

Troubleshooting

Connection Refused

OAuth Client ID Required

Sentry Version Too Old

SSL Certificate Errors

Wrong Instance Being Used

Best Practices